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.

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
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:

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>
time=<rfc3339 | unix_timestamp>
timeout=<duration>
limit=<number>

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.

Data format

The data section of the query result has the following format:

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value> (1)
}

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)\
  },\
  ...\
]

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>
start=<rfc3339 | unix_timestamp>
end=<rfc3339 | unix_timestamp>
step=<duration | float>

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)\
  },\
  ...\
]

Example

This example evaluates the expression up over a 30-second range with a query resolution of 15 seconds:

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

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

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

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

Syntax

GET /api/v1/metadata

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.

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 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": ""\
      }\
    ]
  }
}