The Pushgateway API accepts metrics pushed from short-lived batch jobs and ephemeral processes via HTTP PUT, POST, and DELETE requests. Metrics are organized by job and optional grouping labels, and are exposed for Prometheus scraping until explicitly deleted.
openapi: 3.1.0
info:
title: Prometheus Pushgateway API
description: >-
The Prometheus Pushgateway API accepts metrics pushed from short-lived
batch jobs and ephemeral processes that cannot be scraped by Prometheus
directly. Metrics are organized by job label and optional grouping labels.
Pushed metrics are exposed via a /metrics endpoint for Prometheus to scrape
until explicitly deleted. The Pushgateway supports the Prometheus text
exposition format and OpenMetrics format for metric payloads.
version: v1.9.0
contact:
name: Prometheus Project
url: https://prometheus.io/community/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
description: Prometheus Pushgateway Documentation
url: https://github.com/prometheus/pushgateway/blob/master/README.md
servers:
- url: 'http://{host}:{port}'
description: Pushgateway server
variables:
host:
default: localhost
description: Pushgateway server hostname
port:
default: '9091'
description: Pushgateway server port
tags:
- name: Metrics
description: >-
Endpoints for pushing, replacing, and deleting metric groups. Metrics
are grouped by job and optional additional labels.
- name: Status
description: >-
Endpoints for checking Pushgateway health and retrieving build
information.
paths:
/metrics/job/{job}:
put:
operationId: replaceJobMetrics
summary: Prometheus Replace all metrics for a job
description: >-
Replaces all metrics for the specified job with the metrics in the
request body. The entire group of metrics for the job is atomically
replaced. Use PUT when you want to fully overwrite the existing metric
set for a job.
tags:
- Metrics
parameters:
- $ref: '#/components/parameters/Job'
requestBody:
required: true
content:
text/plain:
schema:
type: string
description: >-
Metrics in Prometheus text exposition format or OpenMetrics
format.
example: "# HELP batch_job_duration_seconds Duration of a batch job.\n# TYPE batch_job_duration_seconds gauge\nbatch_job_duration_seconds 42.0\n"
application/openmetrics-text:
schema:
type: string
description: Metrics in OpenMetrics text format.
responses:
'200':
description: Metrics replaced successfully
'400':
description: Bad request — invalid metric format or labels
post:
operationId: pushJobMetrics
summary: Prometheus Add or update metrics for a job
description: >-
Adds new metrics for the specified job or updates existing metrics.
Unlike PUT, POST only updates the metrics that are present in the
request body while leaving other metrics in the group untouched.
tags:
- Metrics
parameters:
- $ref: '#/components/parameters/Job'
requestBody:
required: true
content:
text/plain:
schema:
type: string
description: Metrics in Prometheus text exposition format.
application/openmetrics-text:
schema:
type: string
description: Metrics in OpenMetrics text format.
responses:
'200':
description: Metrics added or updated successfully
'400':
description: Bad request — invalid metric format or labels
delete:
operationId: deleteJobMetrics
summary: Prometheus Delete all metrics for a job
description: >-
Deletes all metrics for the specified job from the Pushgateway. After
deletion, Prometheus will no longer scrape any metrics for this job
label combination.
tags:
- Metrics
parameters:
- $ref: '#/components/parameters/Job'
responses:
'202':
description: Metrics deletion accepted
'400':
description: Bad request — invalid job label value
/metrics/job/{job}/{labels}:
put:
operationId: replaceGroupedMetrics
summary: Prometheus Replace metrics for a job with grouping labels
description: >-
Replaces all metrics for the specified job and grouping label
combination. Grouping labels are additional key-value pairs appended to
the path as alternating label name and value segments (e.g.,
/metrics/job/myjob/instance/myinstance).
tags:
- Metrics
parameters:
- $ref: '#/components/parameters/Job'
- $ref: '#/components/parameters/Labels'
requestBody:
required: true
content:
text/plain:
schema:
type: string
description: Metrics in Prometheus text exposition format.
application/openmetrics-text:
schema:
type: string
description: Metrics in OpenMetrics text format.
responses:
'200':
description: Metrics replaced successfully
'400':
description: Bad request — invalid metric format or label names
post:
operationId: pushGroupedMetrics
summary: Prometheus Add or update metrics for a job with grouping labels
description: >-
Adds or updates metrics for the specified job and grouping label
combination. Only metrics included in the request body are changed;
other metrics in the group are preserved.
tags:
- Metrics
parameters:
- $ref: '#/components/parameters/Job'
- $ref: '#/components/parameters/Labels'
requestBody:
required: true
content:
text/plain:
schema:
type: string
description: Metrics in Prometheus text exposition format.
responses:
'200':
description: Metrics added or updated successfully
'400':
description: Bad request
delete:
operationId: deleteGroupedMetrics
summary: Prometheus Delete metrics for a job with grouping labels
description: >-
Deletes all metrics for the specified job and grouping label combination.
Only metrics with the exact label set specified in the path are deleted.
tags:
- Metrics
parameters:
- $ref: '#/components/parameters/Job'
- $ref: '#/components/parameters/Labels'
responses:
'202':
description: Metrics deletion accepted
'400':
description: Bad request
/api/v1/metrics:
get:
operationId: listAllMetrics
summary: Prometheus List all pushed metrics
description: >-
Returns all currently stored metric families in JSON format, grouped
by job and grouping labels. This endpoint provides a structured view
of all metrics available for Prometheus to scrape.
tags:
- Metrics
responses:
'200':
description: All pushed metrics returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsResponse'
/-/healthy:
get:
operationId: checkHealth
summary: Prometheus Health check
description: >-
Returns 200 if the Pushgateway is healthy and ready to accept pushed
metrics. Used for liveness probes in Kubernetes deployments.
tags:
- Status
responses:
'200':
description: Pushgateway is healthy
/-/ready:
get:
operationId: checkReady
summary: Prometheus Readiness check
description: >-
Returns 200 when the Pushgateway is ready to serve traffic.
Used for readiness probes in Kubernetes deployments.
tags:
- Status
responses:
'200':
description: Pushgateway is ready
/api/v1/status:
get:
operationId: getStatus
summary: Prometheus Get Pushgateway status
description: >-
Returns build information and runtime status for the Pushgateway
server including version, revision, and configuration flags.
tags:
- Status
responses:
'200':
description: Status returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
components:
parameters:
Job:
name: job
in: path
required: true
description: >-
The job label value for this metric group. This is the primary grouping
key for pushed metrics.
schema:
type: string
example: batch-importer
Labels:
name: labels
in: path
required: true
description: >-
Additional grouping labels as alternating label-name/label-value path
segments (e.g., instance/host1/datacenter/eu).
schema:
type: string
example: instance/server01
schemas:
MetricsResponse:
type: object
description: All currently stored metric groups in the Pushgateway.
properties:
status:
type: string
enum:
- success
- error
data:
type: array
items:
$ref: '#/components/schemas/MetricGroup'
MetricGroup:
type: object
description: A group of metrics sharing the same job and grouping labels.
properties:
labels:
type: object
additionalProperties:
type: string
description: The grouping labels for this metric group including job.
lastPushedAt:
type: string
format: date-time
description: Timestamp of the last push to this group.
metricFamilies:
type: object
description: Map of metric family names to their metric family objects.
additionalProperties:
$ref: '#/components/schemas/MetricFamily'
MetricFamily:
type: object
description: A family of metrics with the same name.
properties:
name:
type: string
description: Metric family name.
help:
type: string
description: Help text describing the metric.
type:
type: string
enum:
- COUNTER
- GAUGE
- SUMMARY
- HISTOGRAM
- UNTYPED
description: Metric type.
metric:
type: array
items:
$ref: '#/components/schemas/Metric'
description: Individual metric instances in this family.
Metric:
type: object
description: An individual metric with labels and value.
properties:
label:
type: array
items:
type: object
properties:
name:
type: string
description: Label name.
value:
type: string
description: Label value.
description: Labels attached to this metric.
gauge:
type: object
properties:
value:
type: number
description: Gauge value.
counter:
type: object
properties:
value:
type: number
description: Counter value.
timestampMs:
type: integer
description: Metric timestamp in milliseconds.
StatusResponse:
type: object
description: Pushgateway build and runtime status.
properties:
status:
type: string
enum:
- success
data:
type: object
properties:
version:
type: string
description: Pushgateway version.
revision:
type: string
description: Git revision.
branch:
type: string
description: Git branch.
buildUser:
type: string
description: User who built this binary.
buildDate:
type: string
description: Build date.
goVersion:
type: string
description: Go version.