> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/observability/monitoring-service/api-how-tos/telemetry-api.md).
# Integration with IONOS CLOUD Telemetry API
The Telemetry API queries metrics about your space.vars.ionos\_cloud servers and is compatible with Prometheus specifications.
The Telemetry API retrieves instance metrics. It is read-only and does not support write operations. The space.vars.ionos\_cloud platform collects these metrics for every server on your contract, eliminating the need for server-side installation or instrumentation.
## Availability and cost
The Telemetry API is available at no additional cost. It becomes available as soon as your contract has at least one observability pipeline, through the managed Grafana provided with the Monitoring Service.
These metrics do not pass through your monitoring pipeline. The Monitoring Service therefore does not bill them as ingested samples, and they do not count toward your sample usage.
## Access the Telemetry API
You can query the Telemetry API through the managed Grafana, or directly over HTTP.
### Endpoint
The Telemetry API uses the following address:
```
https://api.ionos.com/telemetry/api/v1
```
Append one of the supported operations to this address. For example, the following request returns the current processor usage for every server on your contract:
```bash
curl -H "Authorization: Bearer ${TOKEN}" \
"https://api.ionos.com/telemetry/api/v1/query?query=instance_cpu_utilization_average"
```
### Managed Grafana
The managed Grafana in the Monitoring Service comes with a pre-configured datasource for the Telemetry API called **IONOS Telemetry**. You can use this datasource to query metrics from the space.vars.ionos\_cloud Telemetry API using the `GET` HTTP method.
### Authentication
The Telemetry API uses the same authentication as the space.vars.ionos\_cloud API. You can use the same API token to authenticate with the Telemetry API. This means you must update the **IONOS Telemetry** datasource with your API token:
```bash
Header: Authorization Value: Bearer
```
Follow the instructions in [Create new tokens](https://api.ionos.com/docs/authentication/v1/#tag/tokens/operation/tokensGenerate) to generate a token.
After you configure the header, select **Save & test**.
## Available metrics
The Telemetry API exposes the following nine metrics for each server:
| **Metric** | **Type** | **Unit** | **Resource** |
| ---------------------------------- | -------- | ----------------- | ------------ |
| `instance_cpu_utilization_average` | Gauge | Percent, 0 to 100 | Compute |
| `instance_network_in_bytes` | Counter | Bytes | Network |
| `instance_network_out_bytes` | Counter | Bytes | Network |
| `instance_network_in_packets` | Counter | Packets | Network |
| `instance_network_out_packets` | Counter | Packets | Network |
| `instance_volumes_read_bytes` | Counter | Bytes | Storage |
| `instance_volumes_write_bytes` | Counter | Bytes | Storage |
| `instance_volumes_read_ops` | Counter | Operations | Storage |
| `instance_volumes_write_ops` | Counter | Operations | Storage |
Every metric carries the following labels:
| **Label** | **Description** |
| ----------------- | ----------------------------------------------------------------------------- |
| `contract_number` | Your space.vars.ionos\_cloud contract number. |
| `dc` | The physical location of the server, such as `fra` or `txl`. |
| `uuid` | The unique identifier of the server. |
## Query the metrics
### Counters and gauges
`instance_cpu_utilization_average` is a gauge, so you can query it directly. The other eight metrics are cumulative counters, and their raw value is a total that only ever rises. To read them as a rate, wrap them in the PromQL `rate` function:
```
rate(instance_network_in_bytes[5m]) * 8 # Inbound bits per second
rate(instance_volumes_write_ops[5m]) # Write operations per second
instance_cpu_utilization_average # Gauge, query it directly
```
To read a single server, filter on its `uuid`:
```
instance_cpu_utilization_average{uuid="17507c12-0eab-47f3-847b-59dba5bc5abe"}
```
{% hint style="warning" %}
**Important:** Graphing a counter without `rate` produces a line that climbs continuously and does not describe current activity. Use `rate` for all metrics except `instance_cpu_utilization_average`.
{% endhint %}
### Identify a server
Metrics identify each server by `uuid` and carry no server name, so query results and dashboard legends show identifiers rather than names.
To resolve a UUID to a server name, use the space.vars.ionos\_cloud API. The `dc` label holds a physical location rather than a Virtual Data Center (VDC) identifier, so you can also open the server in the Data Center Designer (DCD) when you already know which VDC contains it. For more information, see [Servers](https://docs.ionos.com/cloud/api-reference/cloud-api-v6/servers/).
## Supported API operations
Although the Prometheus specification contains many more API resources and operations, the Telemetry API selectively supports the following GET operations:
```bash
/api/v1/label
/api/v1/query
/api/v1/query_range
/api/v1/metadata
/api/v1/series
```
## Relationship with the Data Center Designer
While the DCD displays these metrics for individual servers, the Telemetry API makes this data available across your entire contract, enabling you to compare and rank servers and build contract-wide alerts.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.ionos.com/cloud/observability/monitoring-service/api-how-tos/telemetry-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.