Skip to main content
This article explains how to push metrics to a Prometheus Pushgateway using the HTTP endpoint. You can push metrics in two ways:
  • Send an HTTP request directly to the Pushgateway (covered here).
  • Use a Prometheus client library to push metrics programmatically (not covered).
This guide covers URL structure, examples with curl, grouping behavior, and the different HTTP methods (POST, PUT, DELETE) and their semantics.

​
HTTP push URL structure

The Pushgateway accepts metric pushes at an endpoint that encodes a grouping key in the URL path. The grouping key is derived from the job name and any additional label/value pairs encoded as path segments. Pattern: http://<pushgateway_address>:<port>/metrics/job/<job_name>/<label1>/<value1>/<label2>/<value2> Key points:
  • Labels encoded in the path are appended to every pushed metric and form part of the grouping key.
  • The grouping key determines how metrics are grouped for updates and deletions.
  • Always URL-encode label names and values that include special characters (slashes, spaces, etc.).
Reference:

​
Pushing a single metric with curl

Metric data must be sent in Prometheus’ text exposition format. A common pattern is to pipe the metric text into curl with --data-binary @-, which reads the request body from stdin and sends a POST by default. Example: push a simple metric named example_metric with value 4421 under job="db_backup":
Explanation:
  • echo "example_metric 4421" writes the metric in the text exposition format.
  • curl --data-binary @- sends stdin as the request body (POST by default).
  • The URL http://localhost:9091/metrics/job/db_backup sets the grouping key job="db_backup".
Verify the metric is exposed by the Pushgateway:

​
Grouping behavior and label-based grouping keys

Metrics pushed to the same URL path—i.e., the same job and identical label/value path components—belong to the same group. Groups enable updating or deleting a set of metrics together. Example: push two metrics into the same group (job=archive, db=mysql):
Push another group (job=archive, app=web):
Inspect metrics filtered for the archive job:
You will see metrics grouped by the path labels, for example:

​
POST vs PUT vs DELETE — semantics and examples

The HTTP method you use affects how metrics are updated in the target group. Note: curl --data-binary @- sends a POST by default. Use -X PUT or -X DELETE to get PUT or DELETE semantics.

​
POST example

POST a new value for metric_one (replaces only that metric in the archive/app=web group):
Resulting group contents:

​
PUT example

Replace the entire archive/app=web group with only metric_one:
After this PUT, the archive/app=web group will contain only:
All previously stored metrics in that group are removed.

​
DELETE example

Delete the archive/app=web group entirely:
After the DELETE, only metrics from other groups (for example, db=mysql) remain.

​
Recap

  • The grouping key is encoded in the path: job plus any additional label/value path segments.
  • Labels in the path are appended to every pushed metric.
  • Use POST to update specific metric names within a group (non-destructive for other metrics in the group).
  • Use PUT to replace the entire group.
  • Use DELETE to remove the entire group.
  • URL-encode path segments that include special characters.
When using curl --data-binary @-, curl sends a POST request by default. Use -X PUT or -X DELETE when you want the explicit PUT or DELETE semantics.

Watch Video