# 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](https://docs.kloudfuse.com/platform/4.1.0/signals/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. |
| **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

```javascript
{
    "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](https://docs.kloudfuse.com/platform/4.1.0/signals/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 |
| **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:

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

Evaluates an instant query at a single point in time,

[/api/v1/query\_range](https://docs.kloudfuse.com/platform/4.1.0/signals/metrics/api/#range-query)

Evaluates a query over a range of time.

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

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

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

Evaluates the list of label names.

[/api/v1/label/<label\_name>/values](https://docs.kloudfuse.com/platform/4.1.0/signals/metrics/api/#metadata-label-values)

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

[/api/v1/metadata](https://docs.kloudfuse.com/platform/4.1.0/signals/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.

### 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" ]\
         },\
         ...\
      ]
   }
}
```

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

### 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. |

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

### 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>"\
      },\
      ...\
   ]
}
```

### Metadata queries: label names

### Syntax

This endpoint returns a list of label names.

```javascript
GET /api/v1/labels
POST /api/v1/labels
```

### Data format

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