Prometheus labels API

swagger: '2.0'
info:
  version: 0.0.1
  title: Alertmanager admin labels 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: labels
  description: Query label names and values.
paths:
  /labels:
    get:
      tags:
      - labels
      summary: Get label names
      operationId: labels
      parameters:
      - name: start
        in: query
        description: Start timestamp for label names query.
        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 label names query.
        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: match[]
        in: query
        description: Series selector argument.
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
        examples:
          example:
            value:
            - '{job="prometheus"}'
      - name: limit
        in: query
        description: Maximum number of label names to return.
        required: false
        explode: false
        schema:
          type: integer
          format: int64
        examples:
          example:
            value: 100
      responses:
        '200':
          description: Label names retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsOutputBody'
              examples:
                labelNames:
                  summary: List of label names
                  value:
                    data:
                    - __name__
                    - active
                    - address
                    - alertmanager
                    - alertname
                    - alertstate
                    - backend
                    - branch
                    - code
                    - collector
                    - component
                    - device
                    - env
                    - endpoint
                    - fstype
                    - handler
                    - instance
                    - job
                    - le
                    - method
                    - mode
                    - name
                    status: success
        default:
          description: Error retrieving label 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:
      - labels
      summary: Get label names
      operationId: labels-post
      requestBody:
        description: Submit a label names query. This endpoint accepts the same parameters as the GET version.
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LabelsPostInputBody'
            examples:
              allLabels:
                summary: Get all label names
                value: {}
              labelsWithTimeRange:
                summary: Get label names within time range
                value:
                  end: '2026-01-02T13:37:00.000Z'
                  start: '2026-01-02T12:37:00.000Z'
              labelsWithMatch:
                summary: Get label names matching series selector
                value:
                  match[]:
                  - up
                  - process_start_time_seconds{job="prometheus"}
        required: true
      responses:
        '200':
          description: Label names retrieved successfully via POST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsOutputBody'
              examples:
                labelNames:
                  summary: List of label names
                  value:
                    data:
                    - __name__
                    - active
                    - address
                    - alertmanager
                    - alertname
                    - alertstate
                    - backend
                    - branch
                    - code
                    - collector
                    - component
                    - device
                    - env
                    - endpoint
                    - fstype
                    - handler
                    - instance
                    - job
                    - le
                    - method
                    - mode
                    - name
                    status: success
        default:
          description: Error retrieving label 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
  /label/{name}/values:
    get:
      tags:
      - labels
      summary: Get label values
      operationId: label-values
      parameters:
      - name: name
        in: path
        description: Label name.
        required: true
        schema:
          type: string
      - name: start
        in: query
        description: Start timestamp for label values query.
        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 label values query.
        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: match[]
        in: query
        description: Series selector argument.
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
        examples:
          example:
            value:
            - '{job="prometheus"}'
      - name: limit
        in: query
        description: Maximum number of label values to return.
        required: false
        explode: false
        schema:
          type: integer
          format: int64
        examples:
          example:
            value: 1000
      responses:
        '200':
          description: Label values retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelValuesOutputBody'
              examples:
                labelValues:
                  summary: List of values for a label
                  value:
                    data:
                    - alertmanager
                    - blackbox
                    - caddy
                    - cadvisor
                    - grafana
                    - node
                    - prometheus
                    - random
                    status: success
        default:
          description: Error retrieving label values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tsdbNotReady:
                  summary: TSDB not ready
                  value:
                    error: TSDB not ready
                    errorType: internal
                    status: error
  /search/label_names:
    get:
      tags:
      - labels
      summary: Search label names
      operationId: search-label-names
      parameters:
      - name: match[]
        in: query
        description: Series selector argument used to scope label discovery.
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
        examples:
          example:
            value:
            - '{__name__="up"}'
      - name: search[]
        in: query
        description: One or more search terms matched against label names (OR logic).
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
        examples:
          example:
            value:
            - inst
      - 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: start
        in: query
        description: Start timestamp for label 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 label 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 label 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: Label names streamed successfully.
          content:
            application/x-ndjson:
              schema:
                type: string
                description: NDJSON response stream.
              examples:
                labelNamesStream:
                  summary: NDJSON stream of label names
                  value: '{"results":[{"name":"instance"},{"name":"job"}]}

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

                    '
        default:
          description: Error searching label 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:
      - labels
      summary: Search label names
      operationId: search-label-names-post
      requestBody:
        description: Submit a label name search. This endpoint accepts the same parameters as the GET version.
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SearchLabelNamesPostInputBody'
            examples:
              labelsForMetric:
                summary: Search label names for a metric
                value:
                  limit: 20
                  match[]:
                  - '{__name__="http_requests_total"}'
                  search[]:
                  - sta
                  sort_by: score
        required: true
      responses:
        '200':
          description: Label names streamed successfully via POST.
          content:
            application/x-ndjson:
              schema:
                type: string
                description: NDJSON response stream.
              examples:
                labelNamesStream:
                  summary: NDJSON stream of label names
                  value: '{"results":[{"name":"instance"},{"name":"job"}]}

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

                    '
        default:
          description: Error searching label 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
  /search/label_values:
    get:
      tags:
      - labels
      summary: Search label values
      operationId: search-label-values
      parameters:
      - name: label
        in: query
        description: Label name whose values should be searched.
        required: true
        explode: false
        schema:
          type: string
        examples:
          example:
            value: instance
      - name: match[]
        in: query
        description: Series selector argument used to scope label value discovery.
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
        examples:
          example:
            value:
            - up
      - name: search[]
        in: query
        description: One or more search terms matched against label values (OR logic).
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
        examples:
          example:
            value:
            - '909'
      - 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: start
        in: query
        description: Start timestamp for label value 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 label value 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 label values to return.
        required: false
        explode: false
        schema:
          type: integer
          minimum: 1
          format: int64
          default: 100
        examples:
          example:
            value: 10
      - 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: 10
      responses:
        '200':
          description: Label values streamed successfully.
          content:
            application/x-ndjson:
              schema:
                type: string
                description: NDJSON response stream.
              examples:
                labelValuesStream:
                  summary: NDJSON stream of label values
                  value: '{"results":[{"value":"localhost:9090"},{"value":"localhost:9091"}]}

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

                    '
        default:
          description: Error searching label values.
          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:
      - labels
      summary: Search label values
      operationId: search-label-values-post
      requestBody:
        description: Submit a label value search. This endpoint accepts the same parameters as the GET version.
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SearchLabelValuesPostInputBody'
            examples:
              valuesForLabel:
                summary: Search values for a label
                value:
                  label: instance
                  limit: 10
                  match[]:
                  - up
                  search[]:
                  - '909'
                  sort_by: score
        required: true
      responses:
        '200':
          description: Label values streamed successfully via POST.
          content:
            application/x-ndjson:
              schema:
                type: string
                description: NDJSON response stream.
              examples:
                labelValuesStream:
                  summary: NDJSON stream of label values
                  value: '{"results":[{"value":"localhost:9090"},{"value":"localhost:9091"}]}

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

                    '
        default:
          description: Error searching label values 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
components:
  schemas:
    LabelsOutputBody:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
          description: Response status.
          example: success
        data:
          type: array
          items:
            type: string
          example:
          - __name__
          - job
          - instance
        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 with an array of strings.
    SearchLabelNamesPostInputBody:
      type: object
      properties:
        match[]:
          type: array
          items:
            type: string
          description: 'Form field: Series selector argument used to scope label discovery.'
          example:
          - '{__name__="up"}'
        search[]:
          type: array
          items:
            type: string
          description: 'Form field: One or more search terms matched against label names (OR logic).'
          example:
          - inst
        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
      additionalProperties: false
      description: POST request body for label name search.
    LabelValuesOutputBody:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
          description: Response status.
          example: success
        data:
          type: array
          items:
            type: string
          example:
          - __name__
          - job
          - instance
        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 with an array of strings.
    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.
    LabelsPostInputBody:
      type: object
      properties:
        start:
          type: string
          description: 'Form field: The start time of the query.'
          example: '2023-07-21T20:00:00.000Z'
        end:
          type: string
          description: 'Form field: The end time of the query.'
          example: '2023-07-21T21:00:00.000Z'
        match[]:
          type: array
          items:
            type: string
          description: 'Form field: Series selector argument that selects the series from which to read the label names.'
          example:
          - '{job="prometheus"}'
        limit:
          type: integer
          format: int64
          description: 'Form field: The maximum number of label names to return.'
          example: 100
      additionalProperties: false
      description: POST request body for labels query.
    SearchLabelValuesPostInputBody:
      type: object
      properties:
        label:
          type: string
          description: 'Form field: Label name whose values should be searched.'
          example: instance
        match[]:
          type: array
          items:
            type: string
          description: 'Form field: Series selector argument used to scope label value discovery.'
          example:
          - up
        search[]:
          type: array
          items:
            type: string
          description: 'Form field: One or more search terms matched against label values (OR logic).'
          example:
          - '909'
        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
      required:
      - label
      additionalProperties: false
      description: POST request body for label value search.