Skip to main content
Prometheus exposes a well-documented HTTP API you can use to run PromQL queries and retrieve internal configuration and state (alerting rules, recording rules, service discovery, etc.). This API is essential when the built-in web UI is not an option — for example, when building automation, exporting metrics to custom tooling, or integrating with dashboards such as Grafana.
A presentation slide titled "HTTP API" stating that Prometheus provides an HTTP API to execute queries and gather information on alerts, rules, and service-discovery configs. It notes this is useful when the built-in web GUI isn't an option, e.g., for building custom tools or third‑party integrations.
Make sure your Prometheus server is reachable from the host running your API calls. Many production Prometheus instances are restricted by firewall, reverse proxy, or authentication — check your deployment’s network and security configuration before calling the API.

​
Key query endpoints

The primary endpoints for querying metrics are: Replace the placeholder http://<prometheus-ip> with your Prometheus server address (for example, http://localhost:9090 or http://prom.example.com).

​
Instant (single-point) queries

To execute an instant vector query, call the /api/v1/query endpoint and provide the PromQL expression as the query parameter. Using POST avoids URL length limitations and simplifies quoting. Example: query ARP entries for a specific node
  • PromQL: node_arp_entries{instance="192.168.1.168:9100"}
  • Endpoint: http://<prometheus-ip>/api/v1/query
cURL example (POST):
Implementation notes:
  • --data (or -d) triggers a POST request. You can use GET by URL-encoding the query parameter, but POST is usually more convenient for long queries.
  • Wrap the entire --data value in single quotes and use double quotes inside label selectors to avoid shell quoting issues.

​
Querying a specific timestamp

To retrieve the value at a particular point in time, add the time parameter (Unix timestamp with optional fractional seconds, or RFC3339). Example:

​
Example: instant vector query with pretty output

Query CPU seconds for the node job and pipe to jq to pretty-print the JSON:
Sample (trimmed) JSON response after piping to jq:
The value array contains two elements: the timestamp (Unix epoch with fractional seconds) and the metric value as a string.

​
Querying a metric at a given time

Example: fetch node_memory_Active_bytes at a specific timestamp:
Sample (trimmed) JSON response:

​
Range vectors and matrix results

To retrieve a series of samples (a range vector), include a duration selector in the PromQL expression. This returns a resultType of "matrix" where each result has a values array with timestamp/value pairs. Example: last 10 minutes relative to a given time:
If you need an evenly sampled set of points over a time window (for charting or fixed-resolution analysis), use the /api/v1/query_range endpoint with start, end, and step parameters: Example:

​
Summary & quick reference

  • Instant queries: http://<prometheus-ip>/api/v1/query — provide query, optionally time.
  • Range queries (even sampling): http://<prometheus-ip>/api/v1/query_range — provide query, start, end, step.
  • Range vectors in PromQL (e.g., metric[10m]) return "matrix" resultType with values arrays.
  • Pipe responses to jq for readable JSON output.
Prometheus query endpoints accept both GET and POST. Use POST (or --data) for convenience and to avoid URL length issues with long queries.

Watch Video