KEDA Metrics API

openapi: 3.1.0
info:
  title: KEDA Metrics API
  description: >-
    KEDA's Metrics API scaler connects to an HTTP endpoint that exposes a
    numeric metric value, which KEDA uses to drive scaling decisions. The
    endpoint must return a JSON, Prometheus, XML, or YAML response containing
    a metric value at a configured path. KEDA polls the endpoint on a
    configurable interval and compares the extracted value against a threshold
    to determine the desired replica count for the target workload.
    This specification describes the interface that an external HTTP metrics
    endpoint must implement to be compatible with the KEDA Metrics API scaler.
  version: '2.x'
  contact:
    name: KEDA Community
    url: https://keda.sh/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: KEDA Metrics API Scaler Documentation
  url: https://keda.sh/docs/latest/scalers/metrics-api/
servers:
  - url: http://{host}:{port}
    description: External metrics provider endpoint (user-configured)
    variables:
      host:
        default: metrics-api
        description: Hostname or IP of the metrics provider service.
      port:
        default: '8080'
        description: Port the metrics provider listens on.
tags:
  - name: Metrics
    description: >-
      Endpoint returning a numeric metric value that KEDA uses to drive
      autoscaling decisions via the Horizontal Pod Autoscaler.
paths:
  /{metricPath}:
    get:
      operationId: getMetricValue
      summary: KEDA Get metric value
      description: >-
        Returns a JSON (or other format) payload containing a numeric metric
        value that KEDA extracts using the configured valueLocation path
        (GJSON notation). The response can include nested objects; KEDA will
        navigate to the configured path to read the scalar value. The extracted
        value can be an unquoted integer (e.g., 42) or a Kubernetes quantity
        string (e.g., "10Mi"). An optional targetValue or activationValue can
        be compared against this number to determine scaling behavior.
      tags:
        - Metrics
      parameters:
        - $ref: '#/components/parameters/MetricPath'
      responses:
        '200':
          description: Metric value payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'
              examples:
                simple:
                  summary: Simple integer metric
                  value:
                    queue_depth: 42
                nested:
                  summary: Nested metric path
                  value:
                    components:
                      worker:
                        tasks: 12
        '401':
          description: Unauthorized — authentication required
        '403':
          description: Forbidden — insufficient permissions
        '404':
          description: Metric path not found
        '500':
          description: Internal server error retrieving metric
components:
  parameters:
    MetricPath:
      name: metricPath
      in: path
      required: true
      description: >-
        The URL path component configured in the KEDA ScaledObject trigger
        metadata url field. Identifies which metric endpoint to query.
      schema:
        type: string
        example: components/stats
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication for secured metrics endpoints.
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication for secured metrics endpoints.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication via header for secured metrics endpoints.
  schemas:
    MetricsResponse:
      type: object
      description: >-
        Arbitrary JSON object returned by the external metrics endpoint.
        KEDA uses GJSON path notation (configured in valueLocation) to
        extract a single numeric metric value from anywhere in this
        structure. The shape is fully user-defined.
      additionalProperties: true
      example:
        queue_depth: 42
        components:
          worker:
            tasks: 12