# 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 [Service Accounts](https://docs.kloudfuse.com/platform/3.5.0/admin-service-accounts/).

## 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](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#range-query).

Request URL

```javascript
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](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#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](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#start). |
| **7** | **`end=1744830060`**: End time of the measurement, in Epoch. Here, Wednesday, April 16, 2025 7:01:00 PM. See [end](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#end). |
| **8** | **`step=60`**: Size of the discrete time intervals for the stream. See [step](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#step). |

ResponseClick to see template for response listing in JSON

```javascript
{
    "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](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#instant-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

```javascript
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](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#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](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#time). |

## Supported endpoints

This reference describes how to query the following endpoints:

[/api/v1/query](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#instant-query)

Evaluates an instant query at a single point in time,

[/api/v1/query_range](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#range-query)

Evaluates a query over a range of time.

[/api/v1/series](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#metadata-series)

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

[/api/v1/labels](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#metadata-labels)

Evaluates the list of label names.

[/api/v1/label/<label_name>/values](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#metadata-label-values)

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

[/api/v1/metadata](https://docs.kloudfuse.com/platform/3.5.0/metrics-api/#metadata-metric)

Evaluates metadata about metrics currently scraped from targets.

## Instant expression queries

### Syntax

This endpoint evaluates an instant query at a single point in time.

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

```javascript
{
  "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:

```javascript
[\
  {\
    "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

```javascript
$ curl 'http://<domain_name>/api/v1/query?query=up&time=2025-03-01T20:10:51.781Z'
```

Response

```javascript
{
   "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.

```javascript
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

- Series are returned sorted by `metric`. Functions `sort` and `sort_by_label` do not apply to range vectors (matrix).

### Data format

```javascript
{
"resultType": "matrix",
"result": <value>
}
```

### Result format

Range queries return a result type `matrix`. The corresponding `result` property has the following format:

```javascript
[\
  {\
    "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

```javascript
$ 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

```javascript
{
   "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.

```javascript
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

```javascript
$ curl -g 'http://<domain_name>/api/v1/series?' --data-urlencode 'match[]=up' --data-urlencode 'match[]=process_start_time_seconds{job="prometheus"}'
```

Response

```javascript
{
   "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.

```javascript
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

```javascript
$ curl '<domain_name>/api/v1/labels'
```

Response

```javascript
{
    "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.

```javascript
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

```javascript
$ curl http://<domain_name>/api/v1/label/http_status_code/values
```

Response

```javascript
{
   "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

```javascript
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

```javascript
curl -G http://<domain_name>/api/v1/metadata?limit=2
```

Response

```javascript
{
   "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

```javascript
curl -G http://<domain_name>/api/v1/metadata?limit_per_metric=1
```

Response

```javascript
{
  "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

```javascript
curl -G http://<domain_name>/api/v1/metadata?metric=http_requests_total
```

Response

```javascript
{
  "status": "success",
  "data": {
    "http_requests_total": [\
      {\
        "type": "counter",\
        "help": "Number of HTTP requests",\
        "unit": ""\
      },\
      {\
        "type": "counter",\
        "help": "Amount of HTTP requests",\
        "unit": ""\
      }\
    ]
  }
}
```