Prometheus API Skill
Query Prometheus monitoring systems via HTTP API at /api/v1.
Quick Reference
Instant Query
curl 'http://<prometheus>:9090/api/v1/query?query=<promql>&time=<timestamp>'
Range Query
curl 'http://<prometheus>:9090/api/v1/query_range?query=<promql>&start=<ts>&end=<ts>&step=<duration>'
Response Format
All responses return JSON:
{
"status": "success" | "error",
"data": <result>,
"errorType": "<string>",
"error": "<string>",
"warnings": ["<string>"]
}
HTTP codes: 400 (bad params), 422 (expression error), 503 (timeout).
Query Endpoints
| Endpoint |
Purpose |
Key Parameters |
/api/v1/query |
Instant query |
query, time, timeout, limit |
/api/v1/query_range |
Range query |
query, start, end, step, timeout, limit |
/api/v1/format_query |
Format PromQL |
query |
/api/v1/series |
Find series by labels |
match[], start, end, limit |
/api/v1/labels |
List label names |
start, end, match[], limit |
/api/v1/label/<name>/values |
Label values |
start, end, match[], limit |
/api/v1/query_exemplars |
Query exemplars |
query, start, end |
Metadata & Status Endpoints
| Endpoint |
Purpose |
/api/v1/targets |
Target discovery status (state=active|dropped|any) |
/api/v1/targets/metadata |
Metric metadata from targets |
/api/v1/metadata |
All metric metadata |
/api/v1/rules |
Alerting/recording rules |
/api/v1/alerts |
Active alerts |
/api/v1/alertmanagers |
Alertmanager discovery |
/api/v1/status/config |
Current config YAML |
/api/v1/status/flags |
CLI flags |
/api/v1/status/runtimeinfo |
Runtime info |
/api/v1/status/buildinfo |
Build info |
/api/v1/status/tsdb |
TSDB cardinality stats |
/api/v1/status/walreplay |
WAL replay progress |
Admin Endpoints (require --web.enable-admin-api)
| Endpoint |
Method |
Purpose |
/api/v1/admin/tsdb/snapshot |
POST |
Create TSDB snapshot |
/api/v1/admin/tsdb/delete_series |
POST |
Delete series (match[], start, end) |
/api/v1/admin/tsdb/clean_tombstones |
POST |
Clean deleted data |
Common PromQL Patterns
# Rate of counter over 5m
rate(http_requests_total[5m])
# Sum by label
sum by (job) (rate(http_requests_total[5m]))
# Percentile from histogram
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
# Filter by label
up{job="prometheus", instance=~".*:9090"}
# Increase over time
increase(http_requests_total[1h])
# Average over time range
avg_over_time(process_cpu_seconds_total[5m])
Result Types
- vector:
[{"metric": {...}, "value": [timestamp, "value"]}]
- matrix:
[{"metric": {...}, "values": [[ts, "val"], ...]}]
- scalar:
[timestamp, "value"]
- string:
[timestamp, "string"]
Scripts
Query script: scripts/prom_query.py
# Instant query
python scripts/prom_query.py http://localhost:9090 'up'
# Range query
python scripts/prom_query.py http://localhost:9090 'rate(http_requests_total[5m])' \
--start '2024-01-01T00:00:00Z' --end '2024-01-01T01:00:00Z' --step '1m'
# Output: table, json, csv
python scripts/prom_query.py http://localhost:9090 'up' --format table
Health check: scripts/prom_health.py
python scripts/prom_health.py http://localhost:9090
Detailed Reference
For complete API documentation: references/api_reference.md
For PromQL functions: references/promql_functions.md
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: prometheus-api3description: Query and interact with Prometheus HTTP API for monitoring data. Use when Claude needs to query Prometheus metrics, execute PromQL queries, retrieve targets/alerts/rules status, access metadata about series/labels, manage TSDB operations, or troubleshoot monitoring infrastructure. Supports instant queries, range queries, metadata endpoints, admin APIs, and alerting information. Use when this capability is needed.4---56# Prometheus API Skill78Query Prometheus monitoring systems via HTTP API at `/api/v1`.910## Quick Reference1112### Instant Query1314```bash15curl 'http://<prometheus>:9090/api/v1/query?query=<promql>&time=<timestamp>'16```1718### Range Query1920```bash21curl 'http://<prometheus>:9090/api/v1/query_range?query=<promql>&start=<ts>&end=<ts>&step=<duration>'22```2324## Response Format2526All responses return JSON:2728```json29{30 "status": "success" | "error",31 "data": <result>,32 "errorType": "<string>",33 "error": "<string>",34 "warnings": ["<string>"]35}36```3738HTTP codes: `400` (bad params), `422` (expression error), `503` (timeout).3940## Query Endpoints4142| Endpoint | Purpose | Key Parameters |43|----------|---------|----------------|44| `/api/v1/query` | Instant query | `query`, `time`, `timeout`, `limit` |45| `/api/v1/query_range` | Range query | `query`, `start`, `end`, `step`, `timeout`, `limit` |46| `/api/v1/format_query` | Format PromQL | `query` |47| `/api/v1/series` | Find series by labels | `match[]`, `start`, `end`, `limit` |48| `/api/v1/labels` | List label names | `start`, `end`, `match[]`, `limit` |49| `/api/v1/label/<name>/values` | Label values | `start`, `end`, `match[]`, `limit` |50| `/api/v1/query_exemplars` | Query exemplars | `query`, `start`, `end` |5152## Metadata & Status Endpoints5354| Endpoint | Purpose |55|----------|---------|56| `/api/v1/targets` | Target discovery status (`state=active\|dropped\|any`) |57| `/api/v1/targets/metadata` | Metric metadata from targets |58| `/api/v1/metadata` | All metric metadata |59| `/api/v1/rules` | Alerting/recording rules |60| `/api/v1/alerts` | Active alerts |61| `/api/v1/alertmanagers` | Alertmanager discovery |62| `/api/v1/status/config` | Current config YAML |63| `/api/v1/status/flags` | CLI flags |64| `/api/v1/status/runtimeinfo` | Runtime info |65| `/api/v1/status/buildinfo` | Build info |66| `/api/v1/status/tsdb` | TSDB cardinality stats |67| `/api/v1/status/walreplay` | WAL replay progress |6869## Admin Endpoints (require `--web.enable-admin-api`)7071| Endpoint | Method | Purpose |72|----------|--------|---------|73| `/api/v1/admin/tsdb/snapshot` | POST | Create TSDB snapshot |74| `/api/v1/admin/tsdb/delete_series` | POST | Delete series (`match[]`, `start`, `end`) |75| `/api/v1/admin/tsdb/clean_tombstones` | POST | Clean deleted data |7677## Common PromQL Patterns7879```promql80# Rate of counter over 5m81rate(http_requests_total[5m])8283# Sum by label84sum by (job) (rate(http_requests_total[5m]))8586# Percentile from histogram87histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))8889# Filter by label90up{job="prometheus", instance=~".*:9090"}9192# Increase over time93increase(http_requests_total[1h])9495# Average over time range96avg_over_time(process_cpu_seconds_total[5m])97```9899## Result Types100101- **vector**: `[{"metric": {...}, "value": [timestamp, "value"]}]`102- **matrix**: `[{"metric": {...}, "values": [[ts, "val"], ...]}]`103- **scalar**: `[timestamp, "value"]`104- **string**: `[timestamp, "string"]`105106## Scripts107108Query script: `scripts/prom_query.py`109110```bash111# Instant query112python scripts/prom_query.py http://localhost:9090 'up'113114# Range query115python scripts/prom_query.py http://localhost:9090 'rate(http_requests_total[5m])' \116 --start '2024-01-01T00:00:00Z' --end '2024-01-01T01:00:00Z' --step '1m'117118# Output: table, json, csv119python scripts/prom_query.py http://localhost:9090 'up' --format table120```121122Health check: `scripts/prom_health.py`123124```bash125python scripts/prom_health.py http://localhost:9090126```127128## Detailed Reference129130For complete API documentation: [references/api_reference.md](references/api_reference.md)131132For PromQL functions: [references/promql_functions.md](references/promql_functions.md)133134---135> Converted and distributed by [TomeVault](https://tomevault.io/claim/julianobarbosa) — claim your Tome and manage your conversions.136<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io