Metric APIs :: Kloudfuse Docs
Metric APIs
Example
Consider how Kloudfuse constructs a query while you use the Metrics Explorer.
Time Series
Kloudfuse constructs a time series query to run against the /api/v1/query_range endpoint. See Range expression queries.
Request URL
https://<domain_name> \ (1)
/api/v1/query_range? \ (2)
query= \ (3)
avg%20by%20(kube_namespace) \ (4)
(container_cpu_usage{kube_cluster_name=%22demo-2-target%22}) \ (5)
&start=1744815660 \ (6)
&end=1744830060 \ (7)
&step=60s \ (8)
| 1 | <domain_name>: Host that initiates the query. |
| 2 | /api/v1/query_range: Endpoint; notice it is query_range. |
| 3 | query=: Query assignment. |
| 4 | avg%20by%20(kube_namespace): Group by, and the aggregation method |
| 5 | (container_cpu_usage{kube_cluster_name=%22demo-2-target%22}): specifies the metric, and the label/value pair; the syntax is (metric{label=value}). |
| 6 | start=1744815660: Start time of the measurement, in Epoch. Here, April 16, 2025 3:01:00 PM. |
| 7 | end=1744830060: End time of the measurement, in Epoch. Here, Wednesday, April 16, 2025 7:01:00 PM. |
| 8 | step=60: Size of the discrete time intervals for the stream. |
Response
{
"status": "success",
"data": {
"resultType": "matrix",
"result": [\
{\
"metric": {\
"kube_namespace": "alloy"\
},\
"values": [\
[\
1744816800,
"3385771.133878014"\
],\
[\
1744816860,
"3385771.133878014"\
],\
...\
]\
},\
...\
]
}
}
Analytical views
Analytical views ( Top List, Table, and Pie Chart) use the query endpoint. They sample data only at the end of the specified time range.
Here, we used the same parameters as for the previous request; Kloudfuse constructs a different query to run against the /api/v1/query endpoint.
Request URL
https://<domain_name>/ \ (1)
api/v1/query? \ (2)
query= \ (3)
avg%20by%20(kube_namespace) \ (4)
(container_cpu_usage{kube_cluster_name=%22demo-2-target%22}) \ (5)
&time=1744830060 \ (6)
| 1 | <domain_name>: Host that initiates the query. |
| 2 | /api/v1/query: Endpoint; notice it is query. |
| 3 | query=: Query assignment |
| 4 | avg%20by%20(kube_namespace): Group by, and the aggregation method |
| 5 | (container_cpu_usage{kube_cluster_name=%22demo-2-target%22}): specifies the metric, and the label/value pair; the syntax is (metric{label=value}). |
| 6 | time=1744830060: The singular time of measurement, in Epoch. Here, Wednesday, April 16, 2025 7:01:00 PM. |
Supported endpoints
This reference describes how to query the following endpoints:
Evaluates an instant query at a single point in time,
Evaluates a query over a range of time.
Evaluates the list of time series that match the specified label.
Evaluates the list of label names.
/api/v1/label/<label_name>/values
Evaluates the list of label values for the specified label name.
Evaluates metadata about metrics currently scraped from targets.
Instant expression queries
Syntax
This endpoint evaluates an instant query at a single point in time.
GET /api/v1/query
POST /api/v1/query
The query endpoint accepts the following URL parameters:
query=<string>
Prometheus expression query string.
time=<rfc3339 | unix_timestamp>
Evaluation timestamp.
If omitted, uses current server time.
Data format
The data section of the query result has the following format:
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value> (1)
}
| 1 | <value>: The query result data; format depends on the resultType. |
Result format
Instant queries return a result type vector. The corresponding result property has the following format:
[\
{\
"metric": { "<label_name>": "<label_value>", ... }, (1)\
"value": [ <unix_time>, "<sample_value>" ], (2)\
},\
...\
]
| 1 | "metric": { "<label_name>": "<label_value>", …}: The metric queried, and a list of specified label name/value pairs. |
| 2 | Each series has the "value" key. |
Example
This example evaluates the expression up at the time 2025-03-01T20:10:51.781Z:
Request
$ curl 'http://<domain_name>/api/v1/query?query=up&time=2025-03-01T20:10:51.781Z'
Response
{
"status" : "success",
"data" : {
"resultType" : "vector",
"result" : [\
{\
"metric" : {\
"__name__" : "up",\
"job" : "prometheus",\
"instance" : "<domain_name>"\
},\
"value": [ 1435781451.781, "1" ]\
},\
...\
]
}
}
Range expression queries
Syntax
This endpoint evaluates a query over a range of time.
GET /api/v1/query_range
POST /api/v1/query_range
Data format
{
"resultType": "matrix",
"result": <value>
}
Result format
Range queries return a result type matrix. The corresponding result property has the following format:
[\
{\
"metric": { "<label_name>": "<label_value>", ... }, (1)\
"values": [ [ <unix_time>, "<sample_value>" ], ... ] (2)\
},\
...\
]
| 1 | "metric": { "<label_name>": "<label_value>", …}: The metric queried, and a list of specified label name/value pairs. |
| 2 | Each series has the "values" key. |
Metadata queries: series through label matchers
Syntax
This endpoint returns the list of time series that match the specified label set.
GET /api/v1/series
POST /api/v1/series
Data format
The data section of the query result consists of a list of objects that contain the label name/value pairs that identify each series.
Example: Return all series that match the search criteria
The following example returns all series that match either of the selectors up or process_start_time_seconds{job="prometheus"}:
Request
$ curl -g 'http://<domain_name>/api/v1/series?' --data-urlencode 'match[]=up' --data-urlencode 'match[]=process_start_time_seconds{job="prometheus"}'
Response
{
"status" : "success",
"data" : [\
{\
"__name__" : "up",\
"job" : "prometheus",\
"instance" : "<domain_name>"\
},\
...\
]
}
Metadata queries: label names
Syntax
This endpoint returns a list of label names.
GET /api/v1/labels
POST /api/v1/labels
Data format
The data section of the JSON response is a list of string label names.