prometheus_query_range
Execute a PromQL range query to retrieve time-series data points over a specified time range and step, enabling historical metric analysis for graphs or incident investigation.
Instructions
Execute a PromQL range query returning time-series data points.
Wraps GET /api/v1/query_range. Returns one series per matching time
series, each with labels and a list of [timestamp, value] pairs.
Total points across all series are capped at 5000 with a truncation hint.
Prometheus may reject the query with HTTP 422 (bad_data) if the step produces too many data points (> 11,000 per series). Increase the step or narrow the time range if this happens.
Note: The Prometheus API does not support filtering by branch or commit in this endpoint — filters are expressed purely in PromQL label matchers.
Examples:
- Use when: "Show me CPU usage over the last hour with 1-minute resolution"
→ query='rate(node_cpu_seconds_total[5m])', step='1m'.
- Use when: "Graph HTTP error rate for the last 24 hours"
→ query='rate(http_requests_total{status=~"5.."}[5m])',
start='2024-01-15T00:00:00Z', end='2024-01-16T00:00:00Z',
step='5m'.
- Use when: Investigating a past incident — pick the time window of the
incident and use a fine step.
- Don't use when: You only want the current value
(call prometheus_query — faster and simpler).
- Don't use when: You want alert history (call prometheus_list_alerts).
Returns:
dict with query / start / end / step / result_type /
series_count / total_points / truncated /
data (list of series with labels, point_count, values).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | End of range. RFC3339 (e.g. '2024-01-15T11:00:00Z') or Unix timestamp (e.g. '1705316400'). | |
| step | Yes | Query resolution step. Duration string (e.g. '15s', '1m', '5m') or float seconds (e.g. '30'). Prometheus rejects steps that produce more than 11,000 data points per series. | |
| query | Yes | PromQL expression to evaluate over a time range. Examples: 'rate(http_requests_total[5m])', 'node_cpu_seconds_total{mode="idle"}'. | |
| start | Yes | Start of range. RFC3339 (e.g. '2024-01-15T10:00:00Z') or Unix timestamp (e.g. '1705312800'). | |
| instance | No | Target instance name (omit for default instance) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ||
| data | Yes | ||
| step | Yes | ||
| query | Yes | ||
| start | Yes | ||
| truncated | Yes | ||
| result_type | Yes | ||
| series_count | Yes | ||
| total_points | Yes |