Using HTTP API Endpoints
1. Querying Instant Vectors
| Endpoint | Method | Description | Parameters |
|---|---|---|---|
| /api/v1/query | GET/POST | Query a single instant vector at a given timestamp | query (required), time (optional) |
Example: Querying a metric at a specific time
curl "http://localhost:9090/api/v1/query?query=up&time=2023-04-01T10:00:00Z"Example: Querying a metric with default timestamp
curl "http://localhost:9090/api/v1/query?query=up"
Note: The
time parameter is optional and defaults to the current time if not provided.
Example: Response format (JSON)
{
"status": "success",
"data": {
"resultType": "vector",
"result": [
{
"metric": {
"__name__": "up",
"instance": "localhost:9090"
},
"value": [
1680345600,
"1"
]
}
]
}
}2. Querying Range Vectors
| Parameter | Description | Example |
|---|---|---|
| query | The PromQL query string to execute | up{job="prometheus"} |
| start | Start time for the range query (RFC3339 or Unix timestamp) | 2024-01-01T00:00:00Z |
| end | End time for the range query (RFC3339 or Unix timestamp) | 2024-01-01T01:00:00Z |
| step | Interval between samples in the returned vector (e.g. 15s, 1m) | 15s |
| timeout | Maximum time to spend on the query (e.g. 10s) | 10s |
Example: Querying Range Vectors
curl "http://localhost:9090/api/v1/query_range?query=up{job="prometheus"}&start=2024-01-01T00:00:00Z&end=2024-01-01T01:00:00Z&step=15s"
Note: The
query_range endpoint returns data in the matrix format, which is a list of time series with their values over time.
Example: Matrix Response Format
{
"status": "success",
":data": {
"resultType": "matrix",
"result": [
{
"metric": {
"job": "prometheus",
"instance": "localhost:9090"
},
"values": [
[1609459200, "1"],
[1609459215, "1"],
[1609459230, "1"]
]
}
]
}
}3. Getting Series Metadata
| Endpoint | Description | Parameters | Example |
|---|---|---|---|
| /api/v1/series | Retrieve series metadata for a given time range and matchers | match[], start, end |
curl "http://localhost:9090/api/v1/series?match%5B%5D=up&start=2024-01-01T00:00:00Z&end=2024-01-02T00:00:00Z" |
Note: The
match[] parameter is required and must be provided at least once.Example: Querying Series Metadata
{
"status": "success",
"data": [
{
"__name__": "up",
"job": "prometheus",
"instance": "localhost:9090"
},
{
"__name__": "up",
"job": "node_exporter",
"instance": "localhost:9100"
}
]
}4. Finding Label Values
| Endpoint | Description | Parameters | Example |
|---|---|---|---|
| /api/v1/label/:name/values | Retrieves all label values for a given label name. | start, end, match[] |
GET /api/v1/label/environment/values |
Example: Retrieving Label Values with Time Range
curl "http://localhost:9090/api/v1/label/environment/values?start=2023-01-01T00:00:00Z&end=2023-01-02T00:00:00Z"
Note: The
match[] parameter allows filtering by metric name or other labels to narrow down results.
5. Getting All Label Names
| Endpoint | Method | Description |
|---|---|---|
| /api/v1/label/__name__/values | GET |
Returns a list of all metric names (labels) in the Prometheus instance. |
Note: The
__name__ label is a special Prometheus label that represents the metric name.
Example: Response Format
{
"status": "success",
"data": [
"up",
"prometheus_http_requests_total",
"go_goroutines"
]
}6. Querying Targets
| Endpoint | Description | Parameters | Example |
|---|---|---|---|
| /api/v1/targets | Lists all active targets | state=active or state=dropped |
curl "http://localhost:9090/api/v1/targets?state=active" |
| /api/v1/targets/metadata | Lists metadata for targets | match_target={job="prometheus"} |
curl "http://localhost:9090/api/v1/targets/metadata?match_target={job="prometheus"}" |
Note: The
/api/v1/targets endpoint returns a list of all configured targets, including their status and labels.7. Querying Rules
| Rule | Description | Example |
|---|---|---|
| query | Query string to evaluate | up == 1 |
| time | Time for evaluation (optional) | 2023-01-01T00:00:00Z |
| timeout | Timeout for query execution (optional) | 10s |
Note: The
query parameter must be URL-encoded.
Example: Querying with Time
curl "http://localhost:9090/api/v1/query?query=up&time=2023-01-01T00:00:00Z"8. Querying Alerts
| Endpoint | Method | Description | Notes |
|---|---|---|---|
| /api/v1/alerts | GET | Retrieve active alerts from the Prometheus server. | Includes alert state, labels, annotations, and duration. |
| /api/v1/alerts/groups | GET | Retrieve active alerts grouped by their labels. | Useful for organizing alerts in dashboards or monitoring UIs. |
Note: The response includes
alerts array with each alert containing labels, annotations, and activeAt.
9. Checking Health
| Endpoint | Description | Notes |
|---|---|---|
| /-/healthy | Indicates if the Prometheus server is healthy | Returns 200 OK if healthy, 503 Service Unavailable if not |
| /-/ready | Indicates if the Prometheus server is ready to serve requests | Returns 200 OK if ready, 503 Service Unavailable if not |
Note: These endpoints are useful for Kubernetes liveness and readiness probes.
10. Getting Configuration
| Endpoint | Method | Description |
|---|---|---|
| /api/v1/status/config | GET | Returns the current Prometheus configuration in YAML format. |
Note: The configuration is returned in YAML format and includes all active rules, scrape configurations, and alerting rules.
11. Getting Runtime Info
| Endpoint | Description | Example |
|---|---|---|
| /api/v1/status/runtimeinfo | Provides runtime information about the Prometheus server. | GET /api/v1/status/runtimeinfo |
Example: Response Format
{
"status": "success",
"data": {
"startTime": "2024-01-01T00:00:00Z",
"reloadConfigSuccess": true,
"externalLabels": {
"job": "prometheus"
},
"storageRetention": "15d"
}
}12. Managing TSDB
| Endpoint | Description | Notes |
|---|---|---|
| /api/v1/admin/tsdb/delete_series | Deletes a set of series from the TSDB | Requires admin access. Accepts query parameters for matching series. |
| /api/v1/admin/tsdb/clean_tombstones | Cleans up tombstones from the TSDB | Removes deleted series and samples from disk. Can be slow on large datasets. |
| /api/v1/admin/tsdb/snapshot | Creates a snapshot of the TSDB | Creates a point-in-time backup of the TSDB data. Useful for backups and migrations. |
Example: Delete Series
curl -X POST "http://localhost:9090/api/v1/admin/tsdb/delete_series" \
-d "match[]=<metric_name>{label="value"}"
Note: These endpoints are part of the Prometheus Admin API and require appropriate permissions to access.