> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# HTTP API
> Explains Prometheus HTTP API usage including instant and range PromQL queries, endpoints, parameters, examples, and curl usage for automation and integrations.
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](https://grafana.com) 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
| Endpoint | Purpose | Required form data |
| -------------------------- | ------------------------------------------------- | ------------------------------------------- |
| `POST /api/v1/query` | Instant query (single point in time) | `query` (PromQL expression) |
| `POST /api/v1/query` | Instant query at a specific time | `query`, `time` (Unix timestamp or RFC3339) |
| `POST /api/v1/query_range` | Range query (multiple samples across an interval) | `query`, `start`, `end`, `step` |
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:
```bash theme={null}
curl 'http://localhost:9090/api/v1/query' --data 'query=node_arp_entries{instance="192.168.1.168:9100"}'
```
If your Prometheus server is remote, replace `http://localhost:9090` with the appropriate host (for example, `http://:9090`).
Example: query CPU seconds total for targets with `job="node"`, and pretty-print with [`jq`](https://stedolan.github.io/jq/):
```bash theme={null}
curl 'http://localhost:9090/api/v1/query' --data 'query=node_cpu_seconds_total{job="node"}' | jq
```
Example response (truncated):
```json theme={null}
{
"status": "success",
"data": {
"resultType": "vector",
"result": [
{
"metric": {
"__name__": "node_cpu_seconds_total",
"cpu": "0",
"instance": "192.168.1.168:9100",
"job": "node",
"mode": "idle"
},
"value": [
1670382765.652,
"502077.09"
]
},
{
"metric": {
"__name__": "node_cpu_seconds_total",
"cpu": "1",
"instance": "192.168.1.168:9100",
"job": "node",
"mode": "idle"
},
"value": [
1670382765.652,
"502077.09"
]
}
]
}
}
```
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`:
```bash theme={null}
curl 'http://localhost:9090/api/v1/query' \
--data 'query=node_memory_Active_bytes{job="node"}' \
--data 'time=1670380680.132' | jq
```
Example response:
```json theme={null}
{
"status": "success",
"data": {
"resultType": "vector",
"result": [
{
"metric": {
"__name__": "node_memory_Active_bytes",
"instance": "192.168.1.168:9100",
"job": "node"
},
"value": [
1670380680.132,
"1369653248"
]
}
]
}
}
```
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:
```bash theme={null}
curl 'http://localhost:9090/api/v1/query_range' \
--data 'query=node_memory_Active_bytes{job="node"}' \
--data 'start=1670380080.132' \
--data 'end=1670380680.132' \
--data 'step=15' | jq
```
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
| Use case | Example query |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Instant metric value for a `job` | `node_cpu_seconds_total{job="node"}` |
| Instant rate over last 5 minutes | `rate(node_cpu_seconds_total[5m])` |
| Range query to chart a metric | Query via `POST /api/v1/query_range` with `start`, `end`, `step` and `query=node_memory_Active_bytes{job="node"}` |
## 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.
## Links and references
* [Prometheus HTTP API documentation](https://prometheus.io/docs/prometheus/latest/querying/api/)
* [PromQL language overview](https://prometheus.io/docs/prometheus/latest/querying/basics/)
* [Grafana](https://grafana.com)
* [`jq` — Command-line JSON processor](https://stedolan.github.io/jq/)