KEDA Metrics API

openapi: 3.2.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.
  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
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
  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
  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.
externalDocs:
  description: KEDA Metrics API Scaler Documentation
  url: https://keda.sh/docs/latest/scalers/metrics-api/