basePath: /api/v1
definitions:
  conprof.detailResponse:
    properties:
      profile_duration_secs:
        type: integer
      state:
        type: string
      target_profiles:
        items:
          $ref: '#/definitions/conprof.detailResponseProfile'
        type: array
      ts:
        type: integer
    type: object
  conprof.detailResponseProfile:
    properties:
      error:
        type: string
      profile_type:
        type: string
      state:
        type: string
      target:
        $ref: '#/definitions/conprof.detailResponseProfileTarget'
        type: object
    type: object
  conprof.detailResponseProfileTarget:
    properties:
      address:
        type: string
      component:
        type: string
    type: object
  conprof.listResponseItem:
    properties:
      component_num:
        additionalProperties:
          type: integer
        type: object
      profile_duration_secs:
        type: integer
      state:
        type: string
      ts:
        type: integer
    type: object
  k.LabelKey:
    properties:
      key:
        type: string
      labels:
        items:
          type: string
        type: array
    required:
    - key
    - labels
    type: object
  k.Matrix:
    properties:
      data:
        additionalProperties:
          items:
            items:
              type: integer
            type: array
          type: array
        type: object
      keyAxis:
        items:
          $ref: '#/definitions/k.LabelKey'
        type: array
      timeAxis:
        items:
          type: integer
        type: array
    required:
    - data
    - keyAxis
    - timeAxis
    type: object
  keyviz.KeyVisualConfig:
    properties:
      auto_collection_disabled:
        type: boolean
      policy:
        type: string
      policy_kv_separator:
        type: string
    type: object
  slowquery.slowLogRespItem:
    properties:
      backoff_time:
        type: number
      backoff_types:
        type: string
      commit_backoff_time:
        type: number
      commit_time:
        type: number
      compile_time:
        type: number
      connection_id:
        description: 'TODO: Switch back to uint64 when modern browser as well as Swagger
          handles BigInt well.'
        type: string
      cop_proc_addr:
        type: string
      cop_proc_avg:
        type: number
      cop_proc_max:
        type: number
      cop_proc_p90:
        type: number
      cop_time:
        type: number
      cop_wait_addr:
        type: string
      cop_wait_avg:
        type: number
      cop_wait_max:
        type: number
      cop_wait_p90:
        type: number
      db:
        type: string
      digest:
        type: string
      disk_max:
        type: integer
      exec_retry_time:
        type: number
      get_commit_ts_time:
        type: number
      host:
        type: string
      ia_remote_read_segment_count:
        type: integer
      ia_remote_read_segment_size:
        type: integer
      ia_remote_read_segment_wait_time:
        type: number
      index_names:
        type: string
      instance:
        type: string
      is_internal:
        description: Basic
        type: integer
      local_latch_wait_time:
        type: number
      lock_keys_time:
        type: number
      memory_max:
        type: integer
      optimize_time:
        type: number
      parse_time:
        type: number
      plan:
        type: string
      plan_from_binding:
        type: integer
      plan_from_cache:
        type: integer
      prepared:
        type: integer
      preproc_subqueries_time:
        type: number
      prev_stmt:
        description: Detail
        type: string
      prewrite_region:
        type: integer
      prewrite_time:
        type: number
      process_keys:
        type: integer
      process_time:
        description: Time
        type: number
      query:
        type: string
      query_time:
        description: latency
        type: number
      read_pool_task_details:
        type: string
      request_count:
        description: Coprocessor
        type: integer
      resolve_lock_time:
        type: number
      resource_group:
        type: string
      rewrite_time:
        type: number
      rocksdb_block_cache_hit_count:
        type: integer
      rocksdb_block_read_byte:
        type: integer
      rocksdb_block_read_count:
        type: integer
      rocksdb_delete_skipped_count:
        description: RocksDB
        type: integer
      rocksdb_key_skipped_count:
        type: integer
      ru:
        description: Resource Control
        type: number
      ru_v2:
        type: number
      stats:
        type: string
      success:
        type: integer
      tidb_cpu_time:
        type: number
      tikv_cpu_time:
        type: number
      time_queued_by_rc:
        type: number
      timestamp:
        description: finish time
        type: number
      total_keys:
        type: integer
      txn_retry:
        type: integer
      txn_start_ts:
        description: 'TODO: Switch back to uint64 when modern browser as well as Swagger
          handles BigInt well.'
        type: string
      user:
        description: Connection
        type: string
      wait_prewrite_binlog_time:
        type: number
      wait_time:
        type: number
      wait_ts:
        type: number
      warnings:
        type: string
      write_keys:
        description: Transaction
        type: integer
      write_size:
        type: integer
      write_sql_response_total:
        type: number
    type: object
  slowquery.slowMetricSeriesPoint:
    items:
      type: integer
    type: array
  slowstats.SlowStats:
    properties:
      avg_disk:
        type: number
      avg_latency:
        type: number
      avg_memory:
        type: number
      count:
        type: integer
      db:
        type: string
      max_disk:
        type: number
      max_latency:
        type: number
      max_memory:
        type: number
      sql_digest:
        type: string
      sql_text:
        type: string
      statement_type:
        type: string
      sum_disk:
        type: number
      sum_latency:
        type: number
      sum_memory:
        type: number
    type: object
  sqls.StatementsDataSourcesResponse:
    properties:
      v2_available:
        type: boolean
    type: object
  sqls.StatementsSummaryEnvelope:
    properties:
      data:
        items:
          $ref: '#/definitions/sqls.StatementsSummaryItem'
        type: array
      status:
        type: string
    type: object
  sqls.StatementsSummaryItem:
    properties:
      db:
        type: string
      dimension:
        type: string
      duration_ns:
        type: integer
      duration_per_exec_ms:
        type: number
      exec_count:
        type: integer
      exec_count_per_sec:
        type: number
      is_other:
        type: boolean
      order_metric:
        description: OrderMetric is the digest-level value used for Top N ranking
          (same as top_digests.order_metric).
        type: number
      plan_digest:
        type: string
      sql_digest:
        type: string
      sql_text:
        type: string
      stmt_type:
        type: string
      table:
        type: string
      timestamp_sec:
        items:
          type: integer
        type: array
      total_ru:
        type: number
      user:
        type: string
      value_by_time:
        description: ValueByTime is one value per time_bucket, aggregated with the
          same expression as order_by (e.g. sum_ru, exec_count, sum_latency).
        items:
          type: number
        type: array
    type: object
  sqls.StatementsTopStatsEnvelope:
    properties:
      data:
        items:
          $ref: '#/definitions/sqls.StatementsTopStatsItem'
        type: array
      status:
        type: string
    type: object
  sqls.StatementsTopStatsItem:
    properties:
      db:
        type: string
      digest_text:
        type: string
      dimension:
        type: string
      exec_count:
        type: integer
      key:
        description: Compatibility field; prefer dimension-specific fields below.
        type: string
      order_by:
        type: string
      plan_count:
        type: integer
      query_sample_text:
        type: string
      sql_digest:
        type: string
      stmt_type:
        type: string
      sum_latency:
        type: integer
      table:
        type: string
      total_ru:
        description: Compatibility field; total_ru is only populated when order_by
          is sum_ru or sum_ru_v2.
        type: number
      user:
        type: string
      value:
        type: number
    type: object
  topru.TopRUSummaryItem:
    properties:
      duration_ns:
        type: integer
      duration_per_exec_ms:
        type: number
      exec_count:
        type: integer
      exec_count_per_sec:
        type: number
      sql_digest:
        type: string
      sql_text:
        type: string
      timestamp_sec:
        items:
          type: integer
        type: array
      total_ru:
        type: number
      total_ru_by_time:
        items:
          type: number
        type: array
    type: object
  topru.TopRUSummaryPlanItem:
    properties:
      duration_ns:
        type: integer
      duration_per_exec_ms:
        type: number
      exec_count:
        type: integer
      exec_count_per_sec:
        type: number
      plan_digest:
        type: string
      plan_text:
        type: string
      sql_digest:
        type: string
      sql_text:
        type: string
      timestamp_sec:
        items:
          type: integer
        type: array
      total_ru:
        type: number
      total_ru_by_time:
        items:
          type: number
        type: array
    type: object
  topru.UserStatsItem:
    properties:
      duration_ns:
        type: integer
      exec_count:
        type: integer
      total_ru:
        type: number
      user:
        type: string
    type: object
  topru.configResponse:
    properties:
      enable:
        type: boolean
    type: object
  topru.summaryEnvelope:
    properties:
      data:
        items:
          $ref: '#/definitions/topru.TopRUSummaryItem'
        type: array
      status:
        type: string
    type: object
  topru.summaryPlanEnvelope:
    properties:
      data:
        items:
          $ref: '#/definitions/topru.TopRUSummaryPlanItem'
        type: array
      status:
        type: string
    type: object
  topru.userStatsEnvelope:
    properties:
      data:
        items:
          $ref: '#/definitions/topru.UserStatsItem'
        type: array
      status:
        type: string
    type: object
  topsqlv2.InstanceItem:
    properties:
      instance:
        type: string
      instance_type:
        type: string
    type: object
  topsqlv2.SummaryByItem:
    properties:
      cpu_time_ms:
        items:
          type: integer
        type: array
      cpu_time_ms_sum:
        type: integer
      logical_io_bytes:
        items:
          type: integer
        type: array
      logical_io_bytes_sum:
        type: integer
      logical_read_bytes:
        items:
          type: integer
        type: array
      logical_read_bytes_sum:
        type: integer
      logical_write_bytes:
        items:
          type: integer
        type: array
      logical_write_bytes_sum:
        type: integer
      network_bytes:
        items:
          type: integer
        type: array
      network_bytes_sum:
        type: integer
      network_in_bytes:
        items:
          type: integer
        type: array
      network_in_bytes_sum:
        type: integer
      network_out_bytes:
        items:
          type: integer
        type: array
      network_out_bytes_sum:
        type: integer
      rocksdb_block_read_count:
        items:
          type: integer
        type: array
      rocksdb_block_read_count_sum:
        type: integer
      text:
        type: string
      timestamp_sec:
        items:
          type: integer
        type: array
    type: object
  topsqlv2.SummaryItem:
    properties:
      cpu_time_ms:
        type: integer
      duration_per_exec_ms:
        type: number
      exec_count_per_sec:
        type: number
      is_other:
        type: boolean
      keyspace:
        description: Keyspace is set for premium TiKV summaries so callers can map
          a query to its TiDB cluster.
        type: string
      logical_io_bytes:
        type: integer
      logical_read_bytes:
        type: integer
      logical_write_bytes:
        type: integer
      network_bytes:
        type: integer
      network_in_bytes:
        type: integer
      network_out_bytes:
        type: integer
      plans:
        items:
          $ref: '#/definitions/topsqlv2.SummaryPlanItem'
        type: array
      rocksdb_block_read_count:
        type: integer
      scan_indexes_per_sec:
        type: number
      scan_records_per_sec:
        type: number
      sql_digest:
        type: string
      sql_text:
        type: string
    type: object
  topsqlv2.SummaryPlanItem:
    properties:
      cpu_time_ms:
        items:
          type: integer
        type: array
      duration_per_exec_ms:
        type: number
      exec_count_per_sec:
        type: number
      logical_io_bytes:
        items:
          type: integer
        type: array
      logical_read_bytes:
        items:
          type: integer
        type: array
      logical_write_bytes:
        items:
          type: integer
        type: array
      network_bytes:
        items:
          type: integer
        type: array
      network_in_bytes:
        items:
          type: integer
        type: array
      network_out_bytes:
        items:
          type: integer
        type: array
      plan_digest:
        type: string
      plan_text:
        type: string
      rocksdb_block_read_count:
        items:
          type: integer
        type: array
      scan_indexes_per_sec:
        type: number
      scan_records_per_sec:
        type: number
      timestamp_sec:
        items:
          type: integer
        type: array
    type: object
  topsqlv2.configResponse:
    properties:
      enable:
        type: boolean
    type: object
  topsqlv2.instancesEnvelope:
    properties:
      data:
        items:
          $ref: '#/definitions/topsqlv2.InstanceItem'
        type: array
      status:
        type: string
    type: object
  topsqlv2.summaryEnvelope:
    properties:
      data:
        items:
          $ref: '#/definitions/topsqlv2.SummaryItem'
        type: array
      data_by:
        items:
          $ref: '#/definitions/topsqlv2.SummaryByItem'
        type: array
      status:
        type: string
    type: object
host: localhost:8081
info:
  contact: {}
  description: 'API for TiDB Cloud Observability diagnosis: TopSQL, TopRU, Slow Query,
    Key Visualizer, Statements, Continuous Profiling. For AI and human developers.'
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: Diagnosis Query API
  version: "1.0"
paths:
  /continuous_profiling/action_token:
    get:
      description: Generate a signed token used by the download and single-view endpoints
        to authorize profiling file generation.
      parameters:
      - description: 'Cloud provider where profiling data is stored: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where the profiling bucket is deployed
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: Raw query string for the target profile, e.g. ts=...&address=...&component=...&profile_type=...
        in: query
        name: q
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            type: string
      summary: Create a token for profile download/view
      tags:
      - conprof
  /continuous_profiling/download:
    get:
      description: Download the requested profiling data as a ZIP file (including
        a README) for offline analysis.
      parameters:
      - description: Signed token generated by /continuous_profiling/action_token
        in: query
        name: token
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            type: file
      summary: Download the selected profile as a ZIP
      tags:
      - conprof
  /continuous_profiling/group_profile/detail:
    get:
      description: Fetch the target profiles inside a continuous profiling group at
        the given timestamp.
      parameters:
      - description: 'Cloud provider where profiling data is stored: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where the profiling bucket is deployed
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: Unix timestamp in seconds identifying the profiling group
        in: query
        name: ts
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/conprof.detailResponse'
      summary: Get details for a specific profiling group
      tags:
      - conprof
  /continuous_profiling/group_profiles:
    get:
      description: List continuous profiling group profiles for a given cluster and
        time window.
      parameters:
      - description: 'Cloud provider where profiling data is stored: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where the profiling bucket is deployed
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: Start time (Unix seconds, inclusive)
        in: query
        name: begin_time
        required: true
        type: integer
      - description: End time (Unix seconds, inclusive)
        in: query
        name: end_time
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/conprof.listResponseItem'
            type: array
      summary: List available continuous profiling groups
      tags:
      - conprof
  /continuous_profiling/single_profile/view:
    get:
      description: Generate a single-profile view artifact that can be consumed by
        speedscope.
      parameters:
      - description: Signed token generated by /continuous_profiling/action_token
        in: query
        name: token
        required: true
        type: string
      responses:
        "200":
          description: OK
          schema:
            type: file
      summary: View the selected profile in speedscope
      tags:
      - conprof
  /keyvisual/config:
    get:
      description: Return Key Visual (TiKV key heatmaps) configuration for diagnosis
        pages.
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/keyviz.KeyVisualConfig'
      summary: Get Key Visual configuration
  /keyvisual/heatmaps:
    get:
      description: Return TiKV usage heatmaps for a key range and time window. The
        `type` controls what signal is visualized.
      parameters:
      - description: Cloud provider where key visualization data is stored (aws or
          gcp)
        in: header
        name: x-provider
        type: string
      - description: Cloud region where key visualization data is stored
        in: header
        name: x-region
        type: string
      - description: Organization ID (x-org-id)
        in: header
        name: x-org-id
        required: true
        type: string
      - description: Project ID (x-project-id)
        in: header
        name: x-project-id
        required: true
        type: string
      - description: Cluster ID (x-cluster-id)
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: Deployment tier (dedicated/shared)
        in: header
        name: x-deploy-type
        type: string
      - description: Environment (e.g. prod)
        in: header
        name: x-env
        required: true
        type: string
      - description: Start key (inclusive) for the key range
        in: query
        name: startkey
        type: string
      - description: End key (exclusive) for the key range
        in: query
        name: endkey
        type: string
      - description: Start time (Unix seconds) for the time range
        in: query
        name: starttime
        type: integer
      - description: End time (Unix seconds) for the time range
        in: query
        name: endtime
        type: integer
      - description: Heatmap signal type
        enum:
        - written_bytes
        - read_bytes
        - written_keys
        - read_keys
        - integration
        in: query
        name: type
        type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/k.Matrix'
      summary: Get Key Visual heatmaps
  /slow_query/available_fields:
    get:
      description: List the available slow query fields that can be requested via
        the `fields` parameter of `/slow_query/list`. Fields are filtered by the cluster's
        slowlog table schema.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where slow logs are stored
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: 'Deployment type: dedicated/shared/nextgen/premium'
        in: header
        name: x-deploy-type
        type: string
      - description: Environment, default prod
        in: header
        name: x-env
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: string
            type: array
      summary: List selectable fields for slow query
      tags:
      - slowquery
  /slow_query/databases:
    get:
      description: Return the database names that have slow queries within a given
        time window.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where slow logs are stored
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: 'Deployment tier: dedicated/shared/nextgen/premium'
        in: header
        name: x-deploy-type
        type: string
      - description: Start time (Unix seconds, inclusive)
        in: query
        name: begin_time
        required: true
        type: integer
      - description: End time (Unix seconds, inclusive)
        in: query
        name: end_time
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: string
            type: array
      summary: List databases with slow queries
      tags:
      - slowquery
  /slow_query/detail:
    get:
      description: Fetch the matched slow query record detail identified by digest,
        timestamp, and connection ID.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where slow logs are stored
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: 'Deployment tier: dedicated/shared/nextgen/premium'
        in: header
        name: x-deploy-type
        type: string
      - description: SQL digest (fingerprint) to match slow log item
        in: query
        name: digest
        required: true
        type: string
      - description: Unix timestamp in seconds to match slow log item
        in: query
        name: timestamp
        required: true
        type: number
      - description: Connection ID to match slow log item
        in: query
        name: connect_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/slowquery.slowLogRespItem'
      summary: Get slow query detail
      tags:
      - slowquery
  /slow_query/list:
    get:
      description: Query slow query logs for a cluster within a time range, with optional
        filtering (digest, databases, fields).
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where slow logs are stored
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: 'Deployment tier: dedicated/shared/nextgen/premium'
        in: header
        name: x-deploy-type
        type: string
      - description: Optional start time (Unix seconds, inclusive)
        in: query
        name: begin_time
        type: integer
      - description: End time (Unix seconds, inclusive)
        in: query
        name: end_time
        required: true
        type: integer
      - description: Comma-separated list of fields to return (e.g. query,timestamp,query_time,memory_max,digest)
        in: query
        name: fields
        required: true
        type: string
      - description: database names to search
        in: query
        items:
          type: string
        name: db
        type: array
      - description: result count limit
        in: query
        name: limit
        type: integer
      - description: Substring filter on SQL text or digest
        in: query
        name: text
        type: string
      - description: order by which field
        in: query
        name: orderBy
        type: string
      - description: descending order
        in: query
        name: desc
        type: boolean
      - description: plan digests to search
        in: query
        items:
          type: string
        name: plans
        type: array
      - description: sql digest to search
        in: query
        name: digest
        type: string
      - description: show internal slow queries
        in: query
        name: show_internal
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/slowquery.slowLogRespItem'
            type: array
      summary: List slow queries
      tags:
      - slowquery
  /slow_query/stats:
    get:
      description: Aggregate slow query statistics over time windows, with optional
        filtering by statement types and databases.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where slow logs are stored
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: hour begin time in unix seconds
        in: query
        name: begin_time
        required: true
        type: integer
      - description: n hours (3/6/12/24/)
        in: query
        name: hours
        required: true
        type: integer
      - description: 'Statement types to include (default: all). Example: [SELECT
          INSERT]'
        in: query
        items:
          type: string
        name: statement_types
        type: array
      - description: statement types not in, default false
        in: query
        name: statement_types_not_in
        type: boolean
      - description: database name, default empty string for all
        in: query
        name: database
        type: string
      - description: database names, default empty array for all
        in: query
        items:
          type: string
        name: databases
        type: array
      - description: order by field, default empty string for count
        in: query
        name: order_by
        type: string
      - description: top limit, default 10
        in: query
        name: limit
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/slowstats.SlowStats'
            type: array
      summary: Get slow query statistics
      tags:
      - slowquery
  /slow_query/stats/databases:
    get:
      description: Return database names present in the aggregated slow query statistics
        window.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where slow logs are stored
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: Hour-aligned begin time (Unix seconds)
        in: query
        name: begin_time
        required: true
        type: integer
      - description: Number of hours to include (3/6/12/24)
        in: query
        name: hours
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: string
            type: array
      summary: List databases for slow query statistics
      tags:
      - slowquery
  /slow_query/stats/metric:
    get:
      description: Fetch a time series metric aggregated from slow queries.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: x-provider
        required: true
        type: string
      - description: Cloud region where slow logs are stored
        in: header
        name: x-region
        required: true
        type: string
      - description: Organization ID in TiDB Cloud (if applicable)
        in: header
        name: x-org-id
        type: string
      - description: Project ID in TiDB Cloud (if applicable)
        in: header
        name: x-project-id
        type: string
      - description: Observability cluster ID for the target TiDB deployment
        in: header
        name: x-cluster-id
        required: true
        type: string
      - description: Hour-aligned begin time (Unix seconds)
        in: query
        name: begin_time
        required: true
        type: integer
      - description: Number of hours to include (3/6/12/24)
        in: query
        name: hours
        required: true
        type: integer
      - description: 'Metric name. Example: count_per_minute (default)'
        in: query
        name: metric_name
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/slowquery.slowMetricSeriesPoint'
            type: array
      summary: Get slow query statistics metric
      tags:
      - slowquery
  /statements/available_fields:
    get:
      description: 'Returns field names for statements APIs. usage=list (default):
        columns for /statements/list fields param; usage=filter: fields for /statements/field_values
        and field+values filters.'
      parameters:
      - description: Cloud provider
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: 'list or filter (default: list)'
        in: query
        name: usage
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: string
            type: array
      summary: List selectable fields for statements
      tags:
      - statements
  /statements/datasource:
    get:
      description: Cheap check that statements v2 Delta Lake data exists (HEAD _delta_log/_last_checkpoint,
        else 00000000000000000000.json). Use before calling list/summary with data_source=v2.
      parameters:
      - description: Cloud provider
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/sqls.StatementsDataSourcesResponse'
      summary: Probe statements v2 data source
      tags:
      - statements
  /statements/field_values:
    get:
      description: Returns distinct values of a field within the time window (JSON
        string array). Use GET /statements/available_fields?usage=filter for allowed
        field names.
      parameters:
      - description: Cloud provider
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: begin_time
        required: true
        type: integer
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end_time
        required: true
        type: integer
      - description: Field name; see available_fields?usage=filter
        in: query
        name: field
        required: true
        type: string
      - description: Max distinct values (default 500, max 2000)
        in: query
        name: limit
        type: integer
      - description: Filter by schemas
        in: query
        items:
          type: string
        name: schemas
        type: array
      - description: Filter by stmt_types
        in: query
        items:
          type: string
        name: stmt_types
        type: array
      - description: Substring filter on SQL text or digest
        in: query
        name: text
        type: string
      - description: Filter rows by user; use sample_users for multi-select
        in: query
        name: sample_user
        type: string
      - description: Filter rows by any of the users (supports sample_users[] / users[])
        in: query
        items:
          type: string
        name: sample_users
        type: array
      - description: Filter rows by table_names (supports tables[] / table_names[])
        in: query
        items:
          type: string
        name: tables
        type: array
      - description: Narrow rows by another field before distinct
        in: query
        name: match_field
        type: string
      - description: Values for match_field
        in: query
        items:
          type: string
        name: match_values
        type: array
      - description: Additional field filters as JSON array
        in: query
        name: filters
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: string
            type: array
      summary: Distinct statement field values
      tags:
      - statements
  /statements/list:
    get:
      description: Return an overview of SQL statements within a time window. The
        returned columns depend on the `fields` parameter.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region where statement data is stored
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID (x-org-id)
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID in TiDB Cloud (optional; defaults to empty)
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID (x-cluster-id) of the target TiDB deployment
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: 'Deployment tier: dedicated or shared'
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: begin_time
        required: true
        type: integer
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end_time
        required: true
        type: integer
      - description: filter by schemas
        in: query
        items:
          type: string
        name: schemas
        type: array
      - description: filter by stmt_types
        in: query
        items:
          type: string
        name: stmt_types
        type: array
      - description: Substring filter on SQL text or digest
        in: query
        name: text
        type: string
      - description: 'Filter rows by user (v2: key in auth_users; v1: exact sample_user
          match); use sample_users for multi-select'
        in: query
        name: sample_user
        type: string
      - description: Filter rows by any of the users (supports sample_users[] / users[])
        in: query
        items:
          type: string
        name: sample_users
        type: array
      - description: Filter rows by table_names (supports tables[] / table_names[])
        in: query
        items:
          type: string
        name: tables
        type: array
      - description: Filter rows by field; see available_fields?usage=filter
        in: query
        name: field
        type: string
      - description: Values for field (supports values[])
        in: query
        items:
          type: string
        name: values
        type: array
      - description: Additional field filters as JSON array
        in: query
        name: filters
        type: string
      - description: Comma-separated list of fields to return. Default includes summary
          fields.
        in: query
        name: fields
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: list of statement rows (schema varies by fields param)
          schema:
            type: object
      summary: List statement overview
      tags:
      - statements
  /statements/plan/detail:
    get:
      description: Returns aggregated detail for a SQL digest, optionally narrowed
        to specific plan_digest values.
      parameters:
      - description: Cloud provider
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: begin_time
        required: true
        type: integer
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end_time
        required: true
        type: integer
      - description: Filter by schema name (substring match)
        in: query
        name: schema_name
        type: string
      - description: SQL digest
        in: query
        name: digest
        required: true
        type: string
      - description: Filter by plan_digest values (supports plans[])
        in: query
        items:
          type: string
        name: plans
        type: array
      - description: Data source identifier
        in: query
        name: dataSource
        type: string
      - description: Data source identifier (alias)
        in: query
        name: data_source
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: aggregated statement detail row
          schema:
            type: object
      summary: Get statement plan detail
      tags:
      - statements
  /statements/plans:
    get:
      description: Returns plan-level aggregates for a SQL digest within a time window.
        One row per plan_digest.
      parameters:
      - description: Cloud provider
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: begin_time
        required: true
        type: integer
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end_time
        required: true
        type: integer
      - description: Filter by schema name (substring match)
        in: query
        name: schema_name
        type: string
      - description: SQL digest
        in: query
        name: digest
        required: true
        type: string
      - description: Data source identifier
        in: query
        name: dataSource
        type: string
      - description: Data source identifier (alias)
        in: query
        name: data_source
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: plan rows grouped by digest and plan_digest
          schema:
            items:
              type: object
            type: array
      summary: List execution plans for a statement
      tags:
      - statements
  /statements/stmt_types:
    get:
      description: Returns supported SQL statement types for statements filtering.
      parameters:
      - description: Cloud provider
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: string
            type: array
      summary: List statement types
      tags:
      - statements
  /statements/summary:
    get:
      description: Returns top-N summary with time-bucketed series (TopRU-like response
        shape). Group by dimension (default digest). For data_source=v2, step defaults
        to 300 (invalid values coerced to 300); begin_time/end_time are aligned to
        300s.
      parameters:
      - description: Cloud provider
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: 'Start time in Unix seconds (inclusive); v2: floored to 300s'
        in: query
        name: begin_time
        required: true
        type: integer
      - description: 'End time in Unix seconds (inclusive); v2: ceiled to 300s'
        in: query
        name: end_time
        required: true
        type: integer
      - description: Filter by schemas
        in: query
        items:
          type: string
        name: schemas
        type: array
      - description: Filter by stmt_types
        in: query
        items:
          type: string
        name: stmt_types
        type: array
      - description: Substring filter on SQL text or digest
        in: query
        name: text
        type: string
      - description: 'Filter rows by user (v2: auth_users key; v1: sample_user); use
          sample_users for multi-select'
        in: query
        name: sample_user
        type: string
      - description: Filter rows by any of the users (supports sample_users[] / users[])
        in: query
        items:
          type: string
        name: sample_users
        type: array
      - description: Filter rows by table_names (supports tables[] / table_names[])
        in: query
        items:
          type: string
        name: tables
        type: array
      - description: Filter rows by field; see available_fields?usage=filter
        in: query
        name: field
        type: string
      - description: Values for field (supports values[])
        in: query
        items:
          type: string
        name: values
        type: array
      - description: Additional field filters as JSON array, e.g. [{\
        in: query
        name: filters
        type: string
      - description: Top N for each ranking list (default 20)
        in: query
        name: top
        type: string
      - description: Sort metric from available fields (numeric subset), e.g. sum_ru|sum_ru_v2|exec_count|sum_latency
        in: query
        name: order_by
        type: string
      - description: 'Group dimension: user | sqltypes | digest | db | table (default:
          digest)'
        in: query
        name: dimension
        type: string
      - description: Time bucket size in seconds (v1 default 60; v2 default 300, invalid
          values coerced to 300)
        in: query
        name: step
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/sqls.StatementsSummaryEnvelope'
      summary: Statements summary statistics
      tags:
      - statements
  /statements/time_ranges:
    get:
      description: Placeholder endpoint for statements time range metadata. Currently
        returns an empty response.
      parameters:
      - description: Cloud provider
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: OK
          schema:
            type: string
      summary: Get statements time ranges
      tags:
      - statements
  /statements/topstats:
    get:
      description: 'Returns ranking list grouped by one dimension: user, sqltypes,
        digest, db (database/schema name), or table.'
      parameters:
      - description: Cloud provider
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: begin_time
        required: true
        type: integer
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end_time
        required: true
        type: integer
      - description: Filter by schemas
        in: query
        items:
          type: string
        name: schemas
        type: array
      - description: Filter by stmt_types
        in: query
        items:
          type: string
        name: stmt_types
        type: array
      - description: Substring filter on SQL text or digest
        in: query
        name: text
        type: string
      - description: 'Filter rows by user (v2: auth_users key; v1: sample_user); use
          sample_users for multi-select'
        in: query
        name: sample_user
        type: string
      - description: Filter rows by any of the users (supports sample_users[] / users[])
        in: query
        items:
          type: string
        name: sample_users
        type: array
      - description: Filter rows by table_names (supports tables[] / table_names[])
        in: query
        items:
          type: string
        name: tables
        type: array
      - description: Filter rows by field; see available_fields?usage=filter
        in: query
        name: field
        type: string
      - description: Values for field (supports values[])
        in: query
        items:
          type: string
        name: values
        type: array
      - description: Additional field filters as JSON array, e.g. [{\
        in: query
        name: filters
        type: string
      - description: Top N rows (default 20)
        in: query
        name: top
        type: string
      - description: 'Group dimension: user | sqltypes | digest | db | table (default:
          digest)'
        in: query
        name: dimension
        type: string
      - description: Sort metric from available fields (numeric subset), e.g. sum_ru|sum_ru_v2|exec_count|sum_latency
        in: query
        name: order_by
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/sqls.StatementsTopStatsEnvelope'
      summary: Statements top statistics
      tags:
      - statements
  /topru/config:
    get:
      description: TopRU is always enabled when using Delta Lake data source
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/topru.configResponse'
      summary: Get config of TopRU
      tags:
      - topru
  /topru/summary:
    get:
      description: Aggregate ReadUnits (RU) grouped by sql_digest within the given
        time range. Plans are collapsed into one row per digest. Use /topru/summaryplan?digest=…
        for plan breakdown.
      parameters:
      - description: Cloud provider where RU data is stored (aws/gcp/azure)
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region where RU data is stored
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID (x-org-id)
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID (x-project-id; optional)
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID (x-cluster-id)
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: 'Deployment tier: dedicated/shared/nextgen/premium'
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: start
        required: true
        type: string
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end
        required: true
        type: string
      - description: Top N SQL digests to return
        in: query
        name: top
        required: true
        type: string
      - description: 'Metric used to rank results: ru | exec_count | duration (default:
          ru)'
        in: query
        name: order_by
        type: string
      - description: Omit to not filter by user. Pass empty (user=) to keep only rows
          with empty or NULL user; pass a name to filter by that user
        in: query
        name: user
        type: string
      - description: 'Data source identifier (expected: deltalake)'
        in: query
        name: data_source
        type: string
      - description: 'Bucket size in seconds. Default: 60'
        in: query
        name: step
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/topru.summaryEnvelope'
      summary: Get TopRU summary (RU by SQL digest)
      tags:
      - topru
  /topru/summaryplan:
    get:
      description: Aggregate ReadUnits (RU) grouped by sql_digest and plan_digest.
        Optionally filter to one sql_digest via digest=.
      parameters:
      - description: Cloud provider where RU data is stored (aws/gcp/azure)
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region where RU data is stored
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID (x-org-id)
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID (x-project-id; optional)
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID (x-cluster-id)
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: 'Deployment tier: dedicated/shared/nextgen/premium'
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: start
        required: true
        type: string
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end
        required: true
        type: string
      - description: Top N SQL/plan groups to return
        in: query
        name: top
        required: true
        type: string
      - description: Filter to a single sql_digest (drill-down from /topru/summary)
        in: query
        name: digest
        type: string
      - description: 'Metric used to rank results: ru | exec_count | duration (default:
          ru)'
        in: query
        name: order_by
        type: string
      - description: Omit to not filter by user. Pass empty (user=) to keep only rows
          with empty or NULL user; pass a name to filter by that user
        in: query
        name: user
        type: string
      - description: 'Data source identifier (expected: deltalake)'
        in: query
        name: data_source
        type: string
      - description: 'Bucket size in seconds. Default: 60'
        in: query
        name: step
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/topru.summaryPlanEnvelope'
      summary: Get TopRU summary by plan (RU by SQL/plan digest)
      tags:
      - topru
  /topru/user_stats:
    get:
      description: Aggregate RU and execution stats grouped by user over the given
        time range.
      parameters:
      - description: Cloud provider where RU data is stored (aws/gcp/azure)
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region where RU data is stored
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID (x-org-id)
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID (x-project-id; optional)
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID (x-cluster-id)
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: Deployment tier
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: start
        required: true
        type: string
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end
        required: true
        type: string
      - description: 'Top N users to return (default: 20)'
        in: query
        name: top
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/topru.userStatsEnvelope'
      summary: Get TopRU user statistics (RU per user)
      tags:
      - topru
  /topsql/available_fields:
    get:
      description: Return order_by field names supported by the given instance's TopSQL
        Delta Lake schema. Optional dimensions (network/logical/rocksdb) are omitted
        when their storage columns are absent.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region where TopSQL data is stored
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID (x-org-id) used to locate TopSQL data
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID in TiDB Cloud (optional; defaults to empty)
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID (x-cluster-id) of the target TiDB deployment
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: 'Deployment tier (used to choose storage adapter): dedicated
          or shared'
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Instance name
        in: query
        name: instance
        required: true
        type: string
      - description: 'Instance type: tidb or tikv'
        in: query
        name: instance_type
        required: true
        type: string
      - description: Must be deltalake for TopSQLv2 schema inspection
        in: query
        name: data_source
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: string
            type: array
      summary: List available TopSQL order_by fields
      tags:
      - topsql
  /topsql/config:
    get:
      description: Return the TopSQL feature configuration for diagnosis queries.
      parameters:
      - description: 'Data source: deltalake enables TopSQLv2 logic; otherwise the
          legacy TopSQL logic'
        in: query
        name: data_source
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/topsqlv2.configResponse'
      summary: Get TopSQL configuration
      tags:
      - topsql
  /topsql/instances:
    get:
      description: List TopSQL instances that have data within the given time window.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region where TopSQL data is stored
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID (x-org-id) used to locate TopSQL data
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID in TiDB Cloud (optional; defaults to empty)
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID (x-cluster-id) of the target TiDB deployment
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: 'Deployment tier (used to choose storage adapter): dedicated
          or shared'
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: start
        required: true
        type: string
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/topsqlv2.instancesEnvelope'
      summary: Get available TopSQL instances
      tags:
      - topsql
  /topsql/summary:
    get:
      description: Return aggregated TopSQL summary for the given time window and
        instance filter.
      parameters:
      - description: 'Cloud provider for the query: aws or gcp'
        in: header
        name: X-Provider
        required: true
        type: string
      - description: Cloud region where TopSQL data is stored
        in: header
        name: X-Region
        required: true
        type: string
      - description: Organization ID (x-org-id) used to locate TopSQL data
        in: header
        name: X-Org-Id
        required: true
        type: string
      - description: Project ID in TiDB Cloud (optional; defaults to empty)
        in: header
        name: X-Project-Id
        type: string
      - description: Cluster ID (x-cluster-id) of the target TiDB deployment
        in: header
        name: X-Cluster-Id
        required: true
        type: string
      - description: 'Deployment tier (used to choose storage adapter): dedicated
          or shared'
        in: header
        name: X-Deploy-Type
        required: true
        type: string
      - description: Start time in Unix seconds (inclusive)
        in: query
        name: start
        required: true
        type: string
      - description: End time in Unix seconds (inclusive)
        in: query
        name: end
        required: true
        type: string
      - description: Aggregation window duration (e.g. 5m, 1h)
        in: query
        name: window
        required: true
        type: string
      - description: Top N results to return
        in: query
        name: top
        required: true
        type: integer
      - description: Instance name filter
        in: query
        name: instance
        required: true
        type: string
      - description: Instance type filter (e.g. tidb, tikv, pd)
        in: query
        name: instance_type
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/topsqlv2.summaryEnvelope'
      summary: Get TopSQL summary
      tags:
      - topsql
schemes:
- http
- https
swagger: "2.0"