How to Retrieve and Process Prometheus Metrics via Its API

1. API format

The stable Prometheus API version is V1, accessed via the path

/api/v1

. It supports GET and POST methods and returns a 2xx status on success. Common error codes include 400 Bad Request, 422 Unprocessable Entity, and 503 Service Unavailable.

Responses are JSON objects with fields such as

status

("success" or "error"),

data

,

errorType

,

error

, and optional

warnings

.

{
  "status": "success" | "error",
  "data": <data>,
  "errorType": "<string>",
  "error": "<string>",
  "warnings": ["<string>"]
}

2. API calls

Instant query

This endpoint performs an expression query and returns data for a single point in time.

GET /api/v1/query
POST /api/v1/query

Parameters:

query= Prometheus expression string.

time= Evaluation timestamp (optional).

timeout= Query timeout (optional, defaults to global

-query.timeout

).

Example: Retrieve the node_load5 value for instance 192.168.214.108 .

curl http://localhost:9090/api/v1/query?query=node_load5{instance="192.168.214.108:9100"}

Sample response:

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "node_load5",
          "instance": "192.168.214.108:9100",
          "job": "node"
        },
        "value": [1666865246.993, "0.04"]
      }
    ]
  }
}

Range query

This endpoint returns data over a specified time range.

GET /api/v1/query_range
POST /api/v1/query_range

Parameters:

query= Prometheus expression string.

start= Start timestamp.

end= End timestamp.

step= Resolution step.

timeout= Query timeout (optional).

Example: Retrieve all node_load5 values for the same instance over a 3‑minute interval.

curl http://localhost:9090/api/v1/query_range?query=node_load5{instance="192.168.214.108:9100"}&start=2022-10-28T02:10:10.000Z&end=2022-10-28T02:13:00.000Z&step=60s

Sample response (matrix result):

{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {
          "__name__": "node_load5",
          "instance": "192.168.214.108:9100",
          "job": "node"
        },
        "values": [
          [1666923010, "0.04"],
          [1666923070, "0.04"],
          [1666923130, "0.03"]
        ]
      }
    ]
  }
}

3. Fetching data with code

For real applications, use a programming language such as Python. First install the

requests

library:

$ pip install requests

Example script

test_api.py

:

# -*- coding: utf-8 -*-
import requests
url = 'http://192.168.214.108:9090'
query_api = '/api/v1/query'
params = 'query=node_load5{instance="192.168.214.108:9100"}'
res = requests.get(url + query_api, params=params)
metrics = res.json().get('data').get('result')
if metrics:
    value = metrics[0].get('value')[1]
    print('服务器 192.168.214.108的node_load5值为 %s' % value)
else:
    print('无法获取有效数据')

Running the script yields:

$ python test_api.py
服务器 192.168.214.108的node_load5值为 0.01

Conclusion

The article demonstrates basic usage of the Prometheus API for instant and range queries and shows how to retrieve metrics programmatically with Python; further API capabilities are documented in the official Prometheus API reference.