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.

Metrics Explorer
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.
Response
Click 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": [...]
            },
            {
                "metric": {
                    "kube_namespace": "datadog-kfuse"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "dd-trace-example"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "field-otel"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "filebeat"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "fluentbit"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "fluentd"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "kf-demo-services"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "kfuse-knight"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "kube-system"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "llm-demo"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "mongo-community"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "newrelic"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "opbeans-go"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "opbeans-python"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "otel-demo-app"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "otel-demo-app-k8s"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "otel-demo-nr"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "otel-demo-nr-kf"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "otel-trace"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "profiler"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "prom"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "sumologic"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "test"
                },
                "values": [...]
            },
            {
                "metric": {
                    "kube_namespace": "test-ingress"
                },
                "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.

Metrics Explorer
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 "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" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "<domain_name>"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

Range expression queries

Syntax

This endpoint evaluates a query over a range of time.

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

The query_range endpoint accepts the following URL parameters:

query=<string>

Prometheus expression query string.

start=<rfc3339 | unix_timestamp>

Start timestamp, inclusive.

end=<rfc3339 | unix_timestamp>

End timestamp, inclusive.

step=<duration | float>

Query resolution step width, in duration format or float number of seconds.

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 are returned sorted by metric. Functions sort and sort_by_label do not apply to range vectors (matrix).

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.

Example

This example evaluates the expression up over a 30-second range with a query resolution of 15 seconds, starting at the time 2025-03-01T20:10:51.781Z and ending at `2025-03-01T20:40:00.781Z:

Request
$ curl 'http://<domain_name>/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
Response
{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "<domain_name>"
            },
            "values" : [
               [ 1740888651.781, "1" ],
               [ 1740889551.781, "1" ],
               [ 1740890451.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "<domain_name>"
            },
            "values" : [
               [ 1740888651.781, "0" ],
               [ 1740889551.781, "0" ],
               [ 1740890451.781, "1" ]
            ]
         }
      ]
   }
}

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

The series endpoint accepts the following URL parameters:

match[]=<series_selector>

Repeated series selector argument that selects which series to return.

Must provide at least one match[] argument.

start=<rfc3339 | unix_timestamp>

Start timestamp.

end=<rfc3339 | unix_timestamp>

End timestamp.

limit=<number>

Maximum number of returned series.

0 means disabled.

Optional.

Limitations

  • When specifying a large or dynamic number of series selectors 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.

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>"
      },
      {
         "__name__" : "up",
         "job" : "node",
         "instance" : "<domain_name>"
      },
      {
         "__name__" : "process_start_time_seconds",
         "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

The labels endpoint accepts the following URL parameters:

start=<rfc3339 | unix_timestamp>

Start timestamp.

Optional.

end=<rfc3339 | unix_timestamp>

End timestamp.

Optional.

match[]=<series_selector>

Repeated series selector argument that selects the series from which to read the label names. Optional.

limit=<number>

Maximum number of returned series.

0 means disabled.

Optional.

Data format

The data section of the JSON response is a list of string label names.

Example: Return the label names

Request
$ curl '<domain_name>/api/v1/labels'
Response
{
    "status": "success",
    "data": [
        "__name__",
        "call",
        "code",
        "config",
        "dialer_name",
        "endpoint",
        "event",
        "goversion",
        "handler",
        "instance",
        "interval",
        "job",
        "le",
        "listener_name",
        "name",
        "quantile",
        "reason",
        "role",
        "scrape_job",
        "slice",
        "version"
    ]
}

Metadata queries: label values

Syntax

This endpoint returns a list of label values for the specified label name.

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

The <label_name>/values endpoint accepts the following URL parameters:

start=<rfc3339 | unix_timestamp>

Start timestamp.

Optional.

end=<rfc3339 | unix_timestamp>

End timestamp.

Optional.

match[]=<series_selector>

Repeated series selector argument that selects the series where to read the label values.

Optional.

limit=<number>

Maximum number of returned series.

0 means disabled.

Optional.

Data format

The data section of the JSON response is a list of string label values.

Example: Query for label values

This example queries all label values for the http_status_code label

Request
$ curl http://<domain_name>/api/v1/label/http_status_code/values
Response
{
   "status" : "success",
   "data" : [
      "200",
      "504"
   ]
}

Metric metadata queries

These queries return metadata about metrics currently scraped from targets. However, they do not provide any target information.

Metric metadata queries are experimental, and may change.

Syntax

GET /api/v1/metadata

The metadata endpoint accepts the following URL parameters:

limit=<number>

Maximum number of metrics to return.

limit_per_metric=<number>

Maximum number of metadata to return for each metric.

metric=<string>

A metric name for filtering metadata. Retrieves all metric metadata if not specified.

Optional.

Data format

The data section of the query result consists of an object where each key is a metric name and each value is a list of unique metadata objects, as exposed for that metric name across all targets.

Example: Return 2 (two) metrics

This example returns two metrics. The metric http_requests_total has more than one object in the list. At least one target has a value for HELP that does not match the rest.

Request
curl -G http://<domain_name>/api/v1/metadata?limit=2
Response
{
   "status": "success",
   "data": {
   "cortex_ring_tokens": [
      {
        "type": "gauge",
        "help": "Number of tokens in the ring",
        "unit": ""
      }
    ],
    "http_requests_total": [
      {
        "type": "counter",
        "help": "Number of HTTP requests",
        "unit": ""
      },
      {
        "type": "counter",
        "help": "Amount of HTTP requests",
        "unit": ""
      }
    ]
  }
}

Example: Return 1 (one) metadata entry for each metric

Request
curl -G http://<domain_name>/api/v1/metadata?limit_per_metric=1
Response
{
  "status": "success",
  "data": {
    "cortex_ring_tokens": [
      {
        "type": "gauge",
        "help": "Number of tokens in the ring",
        "unit": ""
      }
    ],
    "http_requests_total": [
      {
        "type": "counter",
        "help": "Number of HTTP requests",
        "unit": ""
      }
    ]
  }
}

Example: Return metadata for a specified metric

This example returns metadata for the metric http_requests_total.

Request
curl -G http://<domain_name>/api/v1/metadata?metric=http_requests_total
Response
{
  "status": "success",
  "data": {
    "http_requests_total": [
      {
        "type": "counter",
        "help": "Number of HTTP requests",
        "unit": ""
      },
      {
        "type": "counter",
        "help": "Amount of HTTP requests",
        "unit": ""
      }
    ]
  }
}