tools-only Prometheus HTTP API Reference
Complete API documentation for Prometheus /api/v1 endpoints.
Table of Contents
- Expression Queries
- Metadata Endpoints
- Targets & Service Discovery
- Rules & Alerts
- Status Endpoints
- Admin APIs
- Response Formats
Expression Queries
Instant Query
Evaluate expression at single point in time.
GET/POST /api/v1/query
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | Yes | PromQL expression |
time |
rfc3339/unix | No | Evaluation timestamp (default: now) |
timeout |
duration | No | Query timeout |
limit |
number | No | Max series returned (0=disabled) |
Example:
curl 'http://localhost:9090/api/v1/query?query=up&time=2024-01-01T00:00:00Z'
Response:
{
"status": "success",
"data": {
"resultType": "vector",
"result": [
{
"metric": {"__name__": "up", "job": "prometheus", "instance": "localhost:9090"},
"value": [1704067200, "1"]
}
]
}
}
Range Query
Evaluate expression over time range.
GET/POST /api/v1/query_range
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | Yes | PromQL expression |
start |
rfc3339/unix | Yes | Start timestamp (inclusive) |
end |
rfc3339/unix | Yes | End timestamp (inclusive) |
step |
duration/float | Yes | Resolution step width |
timeout |
duration | No | Query timeout |
limit |
number | No | Max series returned |
Example:
curl 'http://localhost:9090/api/v1/query_range?query=up&start=2024-01-01T00:00:00Z&end=2024-01-01T01:00:00Z&step=15s'
Response:
{
"status": "success",
"data": {
"resultType": "matrix",
"result": [
{
"metric": {"__name__": "up", "job": "prometheus"},
"values": [
[1704067200, "1"],
[1704067215, "1"],
[1704067230, "1"]
]
}
]
}
}
Format Query
Prettify PromQL expression.
GET/POST /api/v1/format_query
Example:
curl 'http://localhost:9090/api/v1/format_query?query=foo/bar'
# Returns: "foo / bar"
Metadata Endpoints
Find Series
Return time series matching label sets.
GET/POST /api/v1/series
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
match[] |
series_selector | Yes | Repeated selector (at least one) |
start |
rfc3339/unix | No | Start timestamp |
end |
rfc3339/unix | No | End timestamp |
limit |
number | No | Max series returned |
Example:
curl -g 'http://localhost:9090/api/v1/series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
Label Names
Return all label names.
GET/POST /api/v1/labels
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
start |
rfc3339/unix | No | Start timestamp |
end |
rfc3339/unix | No | End timestamp |
match[] |
series_selector | No | Filter by series |
limit |
number | No | Max labels returned |
Example:
curl 'http://localhost:9090/api/v1/labels'
# Returns: ["__name__", "instance", "job", ...]
Label Values
Return values for specific label.
GET /api/v1/label/<label_name>/values
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
start |
rfc3339/unix | No | Start timestamp |
end |
rfc3339/unix | No | End timestamp |
match[] |
series_selector | No | Filter by series |
limit |
number | No | Max values returned |
Example:
curl 'http://localhost:9090/api/v1/label/job/values'
# Returns: ["prometheus", "node", "alertmanager"]
Metric Metadata
Return metadata for metrics.
GET /api/v1/metadata
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
number | No | Max metrics returned |
limit_per_metric |
number | No | Max metadata per metric |
metric |
string | No | Filter by metric name |
Example:
curl 'http://localhost:9090/api/v1/metadata?metric=http_requests_total'
Response:
{
"status": "success",
"data": {
"http_requests_total": [
{"type": "counter", "help": "Total HTTP requests", "unit": ""}
]
}
}
Targets & Service Discovery
Targets
Return target discovery state.
GET /api/v1/targets
Parameters:
| Parameter | Type | Description |
|---|---|---|
state |
string | Filter: active, dropped, any |
scrapePool |
string | Filter by scrape pool name |
Example:
curl 'http://localhost:9090/api/v1/targets?state=active'
Response:
{
"status": "success",
"data": {
"activeTargets": [
{
"discoveredLabels": {"__address__": "127.0.0.1:9090"},
"labels": {"instance": "127.0.0.1:9090", "job": "prometheus"},
"scrapePool": "prometheus",
"scrapeUrl": "http://127.0.0.1:9090/metrics",
"lastScrape": "2024-01-01T00:00:00Z",
"lastScrapeDuration": 0.05,
"health": "up"
}
],
"droppedTargets": []
}
}
Target Metadata
Return metric metadata from targets.
GET /api/v1/targets/metadata
Parameters:
| Parameter | Type | Description |
|---|---|---|
match_target |
label_selector | Filter targets |
metric |
string | Filter by metric name |
limit |
number | Max targets to match |
Example:
curl -G 'http://localhost:9090/api/v1/targets/metadata' \
--data-urlencode 'metric=go_goroutines' \
--data-urlencode 'match_target={job="prometheus"}'
Rules & Alerts
Rules
Return alerting and recording rules.
GET /api/v1/rules
Parameters:
| Parameter | Type | Description |
|---|---|---|
type |
string | alert or record |
rule_name[] |
string | Filter by rule name |
rule_group[] |
string | Filter by group name |
file[] |
string | Filter by file path |
exclude_alerts |
bool | Exclude active alerts |
match[] |
label_selector | Filter by configured labels |
Example:
curl 'http://localhost:9090/api/v1/rules?type=alert'
Response:
{
"status": "success",
"data": {
"groups": [
{
"name": "example",
"file": "/rules.yaml",
"interval": 60,
"rules": [
{
"name": "HighRequestLatency",
"query": "job:request_latency_seconds:mean5m > 0.5",
"duration": 600,
"labels": {"severity": "page"},
"annotations": {"summary": "High request latency"},
"alerts": [],
"health": "ok",
"type": "alerting"
}
]
}
]
}
}
Alerts
Return active alerts.
GET /api/v1/alerts
Example:
curl 'http://localhost:9090/api/v1/alerts'
Alertmanagers
Return Alertmanager discovery state.
GET /api/v1/alertmanagers
Response:
{
"status": "success",
"data": {
"activeAlertmanagers": [{"url": "http://127.0.0.1:9093/api/v1/alerts"}],
"droppedAlertmanagers": []
}
}
Status Endpoints
Config
GET /api/v1/status/config
Returns currently loaded configuration as YAML.
Flags
GET /api/v1/status/flags
Returns CLI flag values.
Runtime Info
GET /api/v1/status/runtimeinfo
Returns runtime properties (startTime, goroutineCount, storageRetention, etc).
Build Info
GET /api/v1/status/buildinfo
Returns version, revision, branch, buildDate, goVersion.
TSDB Stats
GET /api/v1/status/tsdb?limit=<n>
Returns cardinality statistics:
headStats: numSeries, chunkCount, minTime, maxTimeseriesCountByMetricNamelabelValueCountByLabelNamememoryInBytesByLabelNameseriesCountByLabelValuePair
WAL Replay
GET /api/v1/status/walreplay
Returns WAL replay progress (available before server ready).
Admin APIs
Note: Require --web.enable-admin-api flag.
Snapshot
POST /api/v1/admin/tsdb/snapshot?skip_head=<bool>
Create TSDB snapshot. Returns snapshot directory name.
Delete Series
POST /api/v1/admin/tsdb/delete_series
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
match[] |
series_selector | Yes | Series to delete |
start |
rfc3339/unix | No | Start time (default: min) |
end |
rfc3339/unix | No | End time (default: max) |
Example:
curl -X POST -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
Clean Tombstones
POST /api/v1/admin/tsdb/clean_tombstones
Remove deleted data from disk. Returns 204 on success.
Response Formats
Result Types
Instant Vector (vector):
[
{
"metric": {"__name__": "up", "job": "prometheus"},
"value": [1704067200, "1"]
}
]
Range Vector (matrix):
[
{
"metric": {"__name__": "up", "job": "prometheus"},
"values": [[1704067200, "1"], [1704067215, "1"]]
}
]
Scalar:
[1704067200, "42"]
String:
[1704067200, "hello"]
Native Histogram (experimental)
{
"count": "100",
"sum": "45.5",
"buckets": [
[0, "-0.5", "0.5", "25"],
[1, "0.5", "1.0", "50"]
]
}
Boundary rules: 0=open-left, 1=open-right, 2=open-both, 3=closed-both.
Time & Duration Formats
Timestamps: RFC3339 (2024-01-01T00:00:00Z) or Unix epoch (1704067200)
Durations: ms, s, m, h, d, w, y (e.g., 5m, 1h30m, 7d)
Series Selectors: metric_name{label="value", label2=~"regex.*"}
Label matchers:
=exact match!=not equal=~regex match!~regex not match