Prometheus metadata API

swagger: '2.0'
info:
  version: 0.0.1
  title: Alertmanager admin metadata API
  description: API of the Prometheus Alertmanager (https://github.com/prometheus/alertmanager)
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
basePath: /api/v2/
consumes:
- application/json
produces:
- application/json
tags:
- name: metadata
  description: Retrieve metric metadata such as type and unit.
paths:
  /search/metric_names:
    get:
      tags:
      - metadata
      summary: Search metric names
      operationId: search-metric-names
      parameters:
      - name: match[]
        in: query
        description: Series selector argument used to scope metric discovery.
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
        examples:
          example:
            value:
            - '{job="prometheus"}'
      - name: search[]
        in: query
        description: One or more search terms matched against metric names (OR logic).
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
        examples:
          example:
            value:
            - http_req
      - name: fuzz_threshold
        in: query
        description: Fuzzy threshold in the range 0-100. A value of 0 is the lowest fuzzy threshold.
        required: false
        explode: false
        schema:
          type: integer
          format: int64
        examples:
          example:
            value: 80
      - name: fuzz_alg
        in: query
        description: Fuzzy algorithm. Supported values are subsequence (default) and jarowinkler.
        required: false
        explode: false
        schema:
          type: string
          enum:
          - subsequence
          - jarowinkler
          example: subsequence
      - name: case_sensitive
        in: query
        description: Whether matching is case-sensitive.
        required: false
        explode: false
        schema:
          type: boolean
        examples:
          example:
            value: true
      - name: sort_by
        in: query
        description: Sort mode. Supported values are alpha and score.
        required: false
        explode: false
        schema:
          type: string
          enum:
          - alpha
          - score
          example: alpha
      - name: sort_dir
        in: query
        description: Sort direction. Only valid with sort_by=alpha. Supported values are asc and dsc.
        required: false
        explode: false
        schema:
          type: string
          enum:
          - asc
          - dsc
          example: asc
      - name: include_score
        in: query
        description: Include the relevance score in each result.
        required: false
        explode: false
        schema:
          type: boolean
        examples:
          example:
            value: true
      - name: include_metadata
        in: query
        description: Include metric metadata in each result.
        required: false
        explode: false
        schema:
          type: boolean
        examples:
          example:
            value: true
      - name: start
        in: query
        description: Start timestamp for metric name search.
        required: false
        explode: false
        schema:
          oneOf:
          - type: string
            format: date-time
            description: RFC3339 timestamp.
          - type: number
            format: unixtime
            description: Unix timestamp in seconds.
          description: Timestamp in RFC3339 format or Unix timestamp in seconds.
        examples:
          RFC3339:
            value: '2026-01-02T12:37:00Z'
          epoch:
            value: 1767357420
      - name: end
        in: query
        description: End timestamp for metric name search.
        required: false
        explode: false
        schema:
          oneOf:
          - type: string
            format: date-time
            description: RFC3339 timestamp.
          - type: number
            format: unixtime
            description: Unix timestamp in seconds.
          description: Timestamp in RFC3339 format or Unix timestamp in seconds.
        examples:
          RFC3339:
            value: '2026-01-02T13:37:00Z'
          epoch:
            value: 1767361020
      - name: limit
        in: query
        description: Maximum number of metric names to return.
        required: false
        explode: false
        schema:
          type: integer
          minimum: 1
          format: int64
          default: 100
        examples:
          example:
            value: 20
      - name: batch_size
        in: query
        description: Preferred number of results per NDJSON batch.
        required: false
        explode: false
        schema:
          type: integer
          minimum: 1
          format: int64
          default: 100
        examples:
          example:
            value: 20
      responses:
        '200':
          description: Metric names streamed successfully.
          content:
            application/x-ndjson:
              schema:
                type: string
                description: NDJSON response stream.
              examples:
                metricNamesStream:
                  summary: NDJSON stream of metric names
                  value: '{"results":[{"name":"http_requests_total","type":"counter","help":"Total HTTP requests."}]}

                    {"status":"success","has_more":false}

                    '
        default:
          description: Error searching metric names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tsdbNotReady:
                  summary: TSDB not ready
                  value:
                    error: TSDB not ready
                    errorType: internal
                    status: error
    post:
      tags:
      - metadata
      summary: Search metric names
      operationId: search-metric-names-post
      requestBody:
        description: Submit a metric name search. This endpoint accepts the same parameters as the GET version.
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SearchMetricNamesPostInputBody'
            examples:
              metricAutocomplete:
                summary: Search metric names for autocomplete
                value:
                  include_metadata: true
                  limit: 20
                  search[]:
                  - http_req
                  sort_by: score
        required: true
      responses:
        '200':
          description: Metric names streamed successfully via POST.
          content:
            application/x-ndjson:
              schema:
                type: string
                description: NDJSON response stream.
              examples:
                metricNamesStream:
                  summary: NDJSON stream of metric names
                  value: '{"results":[{"name":"http_requests_total","type":"counter","help":"Total HTTP requests."}]}

                    {"status":"success","has_more":false}

                    '
        default:
          description: Error searching metric names via POST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tsdbNotReady:
                  summary: TSDB not ready
                  value:
                    error: TSDB not ready
                    errorType: internal
                    status: error
  /metadata:
    get:
      tags:
      - metadata
      summary: Get metadata
      operationId: get-metadata
      parameters:
      - name: limit
        in: query
        description: The maximum number of metrics to return.
        required: false
        explode: false
        schema:
          type: integer
          format: int64
        examples:
          example:
            value: 100
      - name: limit_per_metric
        in: query
        description: The maximum number of metadata entries per metric.
        required: false
        explode: false
        schema:
          type: integer
          format: int64
        examples:
          example:
            value: 10
      - name: metric
        in: query
        description: A metric name to filter metadata for.
        required: false
        explode: false
        schema:
          type: string
        examples:
          example:
            value: http_requests_total
      responses:
        '200':
          description: Metric metadata retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataOutputBody'
              examples:
                metricMetadata:
                  summary: Metadata for metrics
                  value:
                    data:
                      go_gc_stack_starting_size_bytes:
                      - help: The stack size of new goroutines. Sourced from /gc/stack/starting-size:bytes.
                        type: gauge
                        unit: ''
                      prometheus_rule_group_iterations_missed_total:
                      - help: The total number of rule group evaluations missed due to slow rule group evaluation.
                        type: counter
                        unit: ''
                      prometheus_sd_updates_total:
                      - help: Total number of update events sent to the SD consumers.
                        type: counter
                        unit: ''
                    status: success
        default:
          description: Error retrieving metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tsdbNotReady:
                  summary: TSDB not ready
                  value:
                    error: TSDB not ready
                    errorType: internal
                    status: error
components:
  schemas:
    SearchMetricNamesPostInputBody:
      type: object
      properties:
        match[]:
          type: array
          items:
            type: string
          description: 'Form field: Series selector argument used to scope metric discovery.'
          example:
          - '{job="prometheus"}'
        search[]:
          type: array
          items:
            type: string
          description: 'Form field: One or more search terms matched against metric names (OR logic).'
          example:
          - http_req
        fuzz_threshold:
          type: integer
          format: int64
          description: 'Form field: Fuzzy threshold in the range 0-100. Default is 0, the lowest fuzzy threshold.'
          example: 80
        fuzz_alg:
          type: string
          enum:
          - subsequence
          - jarowinkler
          description: 'Form field: Fuzzy algorithm. Supported values are subsequence (default) and jarowinkler.'
          example: subsequence
        case_sensitive:
          type: boolean
          description: 'Form field: Whether matching is case-sensitive.'
        sort_by:
          type: string
          enum:
          - alpha
          - score
          description: 'Form field: Sort mode. Supported values are alpha and score. If unset, results are returned in natural order.'
          example: alpha
        sort_dir:
          type: string
          enum:
          - asc
          - dsc
          description: 'Form field: Sort direction. Only valid with sort_by=alpha. Supported values are asc and dsc.'
          example: asc
        include_score:
          type: boolean
          description: 'Form field: Include the relevance score in each result record.'
        start:
          type: string
          description: 'Form field: The start time of the query.'
          example: '2026-01-02T12:37:00.000Z'
        end:
          type: string
          description: 'Form field: The end time of the query.'
          example: '2026-01-02T13:37:00.000Z'
        limit:
          type: integer
          minimum: 1
          format: int64
          description: 'Form field: The maximum number of results to return.'
          default: 100
          example: 20
        batch_size:
          type: integer
          minimum: 1
          format: int64
          description: 'Form field: Preferred number of results per NDJSON batch.'
          default: 100
          example: 20
        include_metadata:
          type: boolean
          description: 'Form field: Include metric metadata in each result.'
      additionalProperties: false
      description: POST request body for metric name search.
    MetadataOutputBody:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
          description: Response status.
          example: success
        data:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Metadata'
        warnings:
          type: array
          items:
            type: string
          description: Only set if there were warnings while executing the request. There will still be data in the data field.
        infos:
          type: array
          items:
            type: string
          description: Only set if there were info-level annotations while executing the request.
      required:
      - status
      - data
      additionalProperties: false
      description: Response body for metadata endpoint.
    Metadata:
      type: object
      properties:
        type:
          type: string
          description: Metric type (counter, gauge, histogram, summary, or untyped).
        unit:
          type: string
          description: Unit of the metric.
        help:
          type: string
          description: Help text describing the metric.
      required:
      - type
      - unit
      - help
      additionalProperties: false
      description: Metric metadata.
    Error:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
          description: Response status.
          example: success
        errorType:
          type: string
          description: Type of error that occurred.
          example: bad_data
        error:
          type: string
          description: Human-readable error message.
          example: invalid parameter
      required:
      - status
      - errorType
      - error
      additionalProperties: false
      description: Error response.