Skip to main content
Prometheus exposes an HTTP API to run PromQL queries and to retrieve server metadata — for example, alerting rules, configuration, and service discovery information. This API is ideal for automation, integrations, or third-party tools like Grafana when the web UI isn’t suitable. Below are concise examples for instant queries (current value), instant queries at a specific timestamp, and range queries (time series across an interval) using the Prometheus HTTP API.

​
Quick reference: endpoints and parameters

Example parameter formats:
  • query — e.g. node_cpu_seconds_total{job="node"} (wrap label selectors in double quotes)
  • time, start, end — Unix timestamp (seconds, optional fractional part) or RFC3339
  • step — resolution in seconds (e.g. 15)
The /api/v1/query endpoint performs an instant query (value at a single point in time). For multi-point time series over a time range, use /api/v1/query_range.
When using curl --data on the shell, wrap the entire value in single quotes and use double quotes inside PromQL label selectors to avoid quoting conflicts. Example: --data 'query=node_cpu_seconds_total{job="node"}'.

​
Instant query (current value)

To evaluate an instant query, POST to /api/v1/query with form-encoded data. Include the query parameter containing a PromQL expression. Example: request the node_arp_entries metric for a specific instance:
If your Prometheus server is remote, replace http://localhost:9090 with the appropriate host (for example, http://<prometheus-host>:9090). Example: query CPU seconds total for targets with job="node", and pretty-print with jq:
Example response (truncated):
Anything available in the web UI can be retrieved via the API by issuing the appropriate PromQL query.

​
Instant query at a specific time

To evaluate an instant query at a historical timestamp, add the time form parameter (Unix timestamp with optional fractional seconds). Prometheus evaluates the expression as of that timestamp. Example: get node_memory_Active_bytes at a specific timestamp and pretty-print with jq:
Example response:
The sample timestamp in the response matches the time you provided.

​
Range query (values over a time interval)

To fetch metric values across an interval (multiple time points), use POST /api/v1/query_range. Required form parameters:
  • query — PromQL expression (often a metric name or function).
  • start — start time (Unix timestamp or RFC3339).
  • end — end time (Unix timestamp or RFC3339).
  • step — resolution step (in seconds; e.g., 15).
Example: fetch node_memory_Active_bytes for the 10 minutes ending at 1670380680.132 with a 15-second step:
The query_range response returns a matrix result: each matched series includes a sequence of [timestamp, value] pairs. Important distinction:
  • Using a range-vector selector inside an instant query (for example, rate(node_cpu_seconds_total[5m])) is valid with /api/v1/query: the function is evaluated over the specified range ending at the instant (or time) you provide.
  • To retrieve multiple samples across time (the actual metric values at each scrape within a range), use /api/v1/query_range.

​
Examples: common usage patterns

​
Summary

  • Use POST /api/v1/query with --data 'query=...' for instant evaluations.
  • Add --data 'time=...' to evaluate an instant query at a specific timestamp.
  • Use POST /api/v1/query_range with start, end, and step to retrieve metric values across a time interval.
  • When using shell curl, wrap the entire --data value in single quotes and use double quotes inside PromQL label selectors to avoid quoting conflicts.

Watch Video