openapi: 3.2.0
info:
  description: 'WARNING: This API is unstable and is meant for experimentation only. Do not

    use this API in production. The endpoints and schemas referenced in this

    documentation will be changed or removed without notice and without any

    backwards compatibility guarantee. Note that even though this API is unstable,

    it is still connected to production data, so use with caution.'
  title: Config Unstable Query Resource Pools API
  version: UNSTABLE
tags:
- name: QueryResourcePools
paths:
  /api/unstable/config/query-resource-pools:
    delete:
      operationId: DeleteQueryResourcePools
      parameters:
      - in: query
        name: dry_run
        schema:
          type: boolean
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/configunstableDeleteQueryResourcePoolsResponse'
        '400':
          description: Cannot delete the QueryResourcePools because it is in use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '404':
          description: Cannot delete the QueryResourcePools because the slug does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        default:
          description: An undefined error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
      tags:
      - QueryResourcePools
      summary: Delete query resource pools
      x-summary-source: derived
    get:
      operationId: ReadQueryResourcePools
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/configunstableReadQueryResourcePoolsResponse'
        '404':
          description: Cannot read the QueryResourcePools because QueryResourcePools has not been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        default:
          description: An undefined error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
      tags:
      - QueryResourcePools
      summary: Read query resource pools
      x-summary-source: derived
    post:
      description: QueryResourcePools CRUD (subset for singleton objects)
      operationId: CreateQueryResourcePools
      responses:
        '200':
          description: A successful response containing the created QueryResourcePools.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/configunstableCreateQueryResourcePoolsResponse'
        '400':
          description: Cannot create the QueryResourcePools because the request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '409':
          description: Cannot create the QueryResourcePools because there is a conflict with an existing QueryResourcePools.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        default:
          description: An undefined error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
      tags:
      - QueryResourcePools
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/configunstableCreateQueryResourcePoolsRequest'
        required: true
      summary: Create query resource pools
      x-summary-source: derived
    put:
      operationId: UpdateQueryResourcePools
      responses:
        '200':
          description: A successful response containing the updated QueryResourcePools.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/configunstableUpdateQueryResourcePoolsResponse'
        '400':
          description: Cannot update the QueryResourcePools because the request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '404':
          description: Cannot update the QueryResourcePools because QueryResourcePools has not been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        default:
          description: An undefined error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/genericError'
      tags:
      - QueryResourcePools
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/configunstableUpdateQueryResourcePoolsRequest'
        required: true
      summary: Update query resource pools
      x-summary-source: derived
components:
  schemas:
    configunstableUpdateQueryResourcePoolsRequest:
      properties:
        query_resource_pools:
          $ref: '#/components/schemas/configunstableQueryResourcePools'
        create_if_missing:
          description: If `true`, the QueryResourcePools will be created if it does not already exist. If `false`, an error will be returned if the QueryResourcePools does not already exist.
          type: boolean
        dry_run:
          description: If `true`, validates the specified configuration without creating or updating the QueryResourcePools. If the specified configuration is valid, the endpoint returns a partial response without the QueryResourcePools. If the specified configuration is invalid, the endpoint returns an error.
          type: boolean
      type: object
    QueryResourcePoolsDefaultPool:
      properties:
        data_read_limit:
          $ref: '#/components/schemas/QueryResourcePoolsDataReadLimit'
      type: object
    QueryResourcePoolsPool:
      properties:
        name:
          description: Name of the pool, which must be unique.
          type: string
        source_types:
          description: 'Source types that map to this pool. A query source maps to the first

            pool, in configured order, whose `source_types` matches its source

            type and whose `source_names` (if set) matches its source name.'
          items:
            $ref: '#/components/schemas/QueryResourcePoolsSourceType'
          type: array
        source_names:
          description: 'Optional. Narrows the pool to specific named sources of the pool''s

            source types: service account IDs for `SERVICE_ACCOUNT`, monitor slugs

            for `MONITOR`, recording rule slugs for `RECORDING_RULE`, and SLO

            slugs for `SLO`.'
          items:
            type: string
          type: array
        data_read_limit:
          $ref: '#/components/schemas/QueryResourcePoolsDataReadLimit'
      type: object
    configunstableQueryResourcePools:
      description: 'QueryResourcePools groups automated metrics query sources (monitors,

        recording rules, SLOs, and service accounts) into pools with per-pool

        datapoints-read rate limits. When a pool sustains usage above its limit for

        the configured sustain period, all of its queries are rejected for a penalty

        period, after which the pool is readmitted. Repeat offenses increase the

        penalty period; sustained good behavior resets it.


        Pools only apply to automated query sources. Queries issued manually (for

        example, from the UI) are never admission-controlled by pools. Query

        sources that don''t match any pool map to the default pool.'
      properties:
        pools:
          description: 'Optional. Pools that group automated query sources. Query sources map to

            the first pool that matches, in configured order.'
          items:
            $ref: '#/components/schemas/QueryResourcePoolsPool'
          type: array
        default_pool:
          $ref: '#/components/schemas/QueryResourcePoolsDefaultPool'
        created_at:
          description: Set in API responses.
          format: date-time
          readOnly: true
          type: string
        updated_at:
          description: Set in API responses.
          format: date-time
          readOnly: true
          type: string
      type: object
    configunstableCreateQueryResourcePoolsResponse:
      properties:
        query_resource_pools:
          $ref: '#/components/schemas/configunstableQueryResourcePools'
      type: object
    apiError:
      properties:
        code:
          description: An optional private error code whose values are undefined.
          format: int32
          type: integer
        message:
          description: An error message describing what went wrong.
          type: string
      type: object
    configunstableDeleteQueryResourcePoolsResponse:
      type: object
    configunstableCreateQueryResourcePoolsRequest:
      properties:
        query_resource_pools:
          $ref: '#/components/schemas/configunstableQueryResourcePools'
        dry_run:
          description: If `true`, validates the specified configuration without creating the QueryResourcePools. If the specified configuration is valid, the endpoint returns a partial response without the QueryResourcePools. If the specified configuration is invalid, the endpoint returns an error.
          type: boolean
      type: object
    configunstableUpdateQueryResourcePoolsResponse:
      properties:
        query_resource_pools:
          $ref: '#/components/schemas/configunstableQueryResourcePools'
      type: object
    configunstableReadQueryResourcePoolsResponse:
      properties:
        query_resource_pools:
          $ref: '#/components/schemas/configunstableQueryResourcePools'
      type: object
    QueryResourcePoolsDataReadLimit:
      description: 'DataReadLimit defines the datapoints-read rate limit for a pool and the

        circuit-breaker behavior applied when the pool exceeds it. If a pool has

        no `data_read_limit`, its consumption is measured but never limited,

        subject only to the tenant-wide query capacity system limits.'
      properties:
        max_datapoints_read_per_second:
          description: 'Maximum datapoints read per second for the pool, aggregated across all

            sources in the pool. This field must be set explicitly; a value of `0`

            blocks all queries from the pool.'
          format: int64
          type: string
        sustain_secs:
          description: 'Optional. How long the pool must remain above

            `max_datapoints_read_per_second` before its queries are rejected. Must

            be a whole multiple of 60 seconds, between 60 and 300; `0` (or

            omitted) applies the 60-second default. Must be omitted when

            `max_datapoints_read_per_second` is `0`, where queries are rejected

            immediately.


            Once a pool trips its limit, all of its queries are rejected for a

            penalty period, which increases on repeated offenses and resets after

            the pool remains under its limit. The penalty behavior is

            system-managed and not configurable.'
          format: int32
          type: integer
      type: object
    QueryResourcePoolsSourceType:
      enum:
      - MONITOR
      - RECORDING_RULE
      - SLO
      - SERVICE_ACCOUNT
      type: string
    genericError:
      additionalProperties: true
      type: object