HTTP API 是什么
Prometheus 对外提供 HTTP 查询接口：/api/v1/query 查瞬时值、/api/v1/query_range 查区间序列、/api/v1/series 列举序列、/api/v1/labels 与 /api/v1/targets 查询元信息。脚本化取数、巡检报告与自建工具集成都走这套接口，返回结构统一，解析成本低。
基本信息
| 基础路径 | /api/v1 |
|---|---|
| 瞬时查询 | /api/v1/query |
| 区间查询 | /api/v1/query_range |
| 列举序列 | /api/v1/series |
| 返回结构 | data.resultType 决定解析方式 |
| 鉴权 | 取决于部署（反向代理或内置机制） |
典型使用场景
- 用脚本定期拉取指标生成日报或巡检报告
- 自建工具按需查询指标，做业务看板或容量评估
- 运维平台上集成查询能力，替代人工点开 Prometheus 界面
- 自动化测试里校验指标是否存在、数值是否在预期范围
- 把查询结果导入表格做离线分析
- 抓取区间数据做自定义算法处理（如异常检测）
curl 示例
curl 示例
# 瞬时查询（用 --data-urlencode 规避转义问题）
curl -G 'http://127.0.0.1:9090/api/v1/query' --data-urlencode 'query=up{job="api"}'
# 区间查询（注意 step 参数）
curl -G 'http://127.0.0.1:9090/api/v1/query_range' \
--data-urlencode 'query=rate(http_requests_total[5m])' \
--data-urlencode 'start=1755000000' --data-urlencode 'end=1755003600' --data-urlencode 'step=15'
# 列举序列
curl -G 'http://127.0.0.1:9090/api/v1/series' --data-urlencode 'match[]=up{job="api"}'常用端点
| 端点 | 用途 | 关键参数 |
|---|---|---|
| /api/v1/query | 瞬时查询 | query、time |
| /api/v1/query_range | 区间查询 | query、start、end、step |
| /api/v1/series | 列举序列 | match[]、start、end |
| /api/v1/labels | 列举标签名 | match[] |
| /api/v1/targets | 抓取目标状态 | state |
返回结构里的 data.resultType 决定解析方式：vector、matrix、scalar、string 形态不同，写解析代码时要先判断类型。
query_range 的 step 太小会因返回点数上限被截断，长区间查询先把 step 放大，再按需要下钻细分时段。
查询参数未做 URL 编码时大括号与引号会破坏请求，统一用 --data-urlencode 或客户端库提供的参数构造方式。
时间参数既可用 Unix 秒也可用 RFC3339 字符串；跨时区脚本建议直接用 Unix 秒，避免时区解析差异。
接口返回的 status 字段要先判断：success 为 false 时 data 不存在，附带 errorType 说明是参数错误还是执行超时，据此分流处理。
/api/v1/targets 与 /api/v1/rules 适合做自动化巡检：把它们接入自建工具，可以定期核对抓取目标与规则是否存在异常。