APIs for Metrics :: Kloudfuse Docs

APIs for Metrics

To interact programmatically with metrics, issue the required query requests to valid endpoints, using PromQL REST APIs GET and POST methods.

The Kloudfuse query is embedded within the PromQL request arguments.

For authorization, see Authorization for API calls.

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, beginning of definition; see query.
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. See start.
7	`end=1744830060`: End time of the measurement, in Epoch. Here, Wednesday, April 16, 2025 7:01:00 PM. See end.
8	`step=60`: Size of the discrete time intervals for the stream. See step.

ResponseClick to see template for response listing in JSON

{
    "status": "success",
    "data": {
        "resultType": "matrix",
        "result": [\
            {\
                "metric": {\
                    "kube_namespace": "alloy"\
                },\
                "values": [\
                    [\
                        1744816800,
                        "3385771.133878014"\
                    ],\
                    [\
                        1744816860,
                        "3385771.133878014"\
                    ],\
                    ...\
                ]\
            },\
            {\
                "metric": {\
                    "kube_namespace": "datadog"\
                },\
                "values": [...]\
            },\
            ...\
        ]
    }
}

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, beginning of definition; see query.
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. See end.

Supported endpoints

This reference describes how to query the following endpoints:

/api/v1/query

Evaluates an instant query at a single point in time,

/api/v1/query_range

Evaluates a query over a range of time.

/api/v1/series

Evaluates the list of time series that match the specified label.

/api/v1/labels

Evaluates the list of label names.

/api/v1/label/<label_name>/values

Evaluates the list of label values for the specified label name.

/api/v1/metadata

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.

Optional.

timeout=<duration>

Evaluation timeout.

Defaults to and is capped by the value of the -query.timeout flag.

Optional.

limit=<number>

Maximum number of returned series.

Doesn’t affect scalars or strings, but truncates the number of series for matrices and vectors. 0 means disabled.

Optional.

Limitations

When specifying a large query that may breach server-side URL character limits, URL-encode query parameters directly in the request body by using the POST method and Content-Type: application/x-www-form-urlencoded header.
JSON does not support special float values, such as NaN, Inf, and -Inf, so sample values are transferred as quoted JSON strings rather than raw numbers.
Series may be returned in any particular order, unless you use a sorting function, sort or sort_by_label.

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	`