> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Prometheus

> Connect Prometheus, Thanos, VictoriaMetrics, or Grafana Cloud for read-only PromQL queries, metric discovery, target health, and alert inspection

Connect your Prometheus-compatible monitoring backend to enable CloudThinker agents to run PromQL queries, discover metrics and labels, inspect scrape-target health, and correlate active alerts — all read-only.

<Info>
  The connector works with any backend that speaks the standard Prometheus HTTP API: self-hosted **Prometheus**, **Thanos**, **VictoriaMetrics**, and **Grafana Cloud**. Authentication supports **None**, **Bearer Token**, and **Basic Auth**.
</Info>

***

## Supported platforms

| Platform            | Support                          | Typical auth           |
| ------------------- | -------------------------------- | ---------------------- |
| **Prometheus**      | Self-hosted, all recent releases | None or Bearer         |
| **Thanos**          | Querier behind an auth proxy     | None, Bearer, or Basic |
| **VictoriaMetrics** | Single-node and cluster          | None or Basic          |
| **Grafana Cloud**   | Prometheus / Mimir endpoint      | Basic                  |

<Note>
  Against managed, Mimir-backed endpoints (Grafana Cloud), the `/api/v1/targets`, `/rules`, and `/alerts` paths are not exposed and return 404. This is expected — the query API (instant queries, range queries, labels, and metadata) works normally.
</Note>

***

## Prerequisites

* A **Prometheus-compatible endpoint** reachable from CloudThinker over HTTPS — self-hosted Prometheus, Thanos, VictoriaMetrics, or Grafana Cloud.
* Credentials if the endpoint requires authentication: a bearer token (Bearer Token mode) or a username and password (Basic Auth mode).
* For **Grafana Cloud**, the numeric instance ID and an access-policy token with the **metrics:read** scope.

***

## Choosing an auth mode

Pick the mode that matches how your endpoint is exposed:

| Mode             | When to use                                                                           | Fields                    |
| ---------------- | ------------------------------------------------------------------------------------- | ------------------------- |
| **None**         | Open or network-restricted endpoint (self-hosted Prometheus inside a private network) | URL only                  |
| **Bearer Token** | Endpoint behind a proxy or gateway that expects `Authorization: Bearer <token>`       | URL + token               |
| **Basic Auth**   | Grafana Cloud, Thanos behind an auth proxy, or VictoriaMetrics with username/password | URL + username + password |

<Tip>
  For **Grafana Cloud**, the username is your numeric instance ID and the password is an access-policy token with metrics read scope.
</Tip>

***

## Setup

<Steps>
  <Step title="Find your Prometheus URL">
    Identify the base URL of your Prometheus HTTP API, e.g. `https://prometheus.your-domain.com` or your Grafana Cloud Prometheus query endpoint. CloudThinker appends the standard `/api/v1/...` paths.
  </Step>

  <Step title="Prepare credentials (if required)">
    * **None** — nothing to prepare; the endpoint is reachable without auth.
    * **Bearer Token** — obtain the bearer token your proxy or gateway expects.
    * **Basic Auth** — obtain the username and password (for Grafana Cloud, the numeric instance ID and an access-policy token).
  </Step>

  <Step title="Add connection in CloudThinker">
    Navigate to **Connections → Prometheus** and enter:

    * **PROMETHEUS\_URL**: your endpoint, e.g. `https://prometheus.your-domain.com`
    * **PROMETHEUS\_AUTH\_TYPE**: select **None**, **Bearer Token**, or **Basic Auth**

    The credential fields appear based on your selection:

    * **Bearer Token** → **PROMETHEUS\_TOKEN**
    * **Basic Auth** → **PROMETHEUS\_USERNAME** and **PROMETHEUS\_PASSWORD**

    Click **Connect**. CloudThinker verifies the endpoint and shows a **Connected** status.
  </Step>
</Steps>

***

## Connection details

| Field                      | Description                                                          | Example                              |
| -------------------------- | -------------------------------------------------------------------- | ------------------------------------ |
| **PROMETHEUS\_URL**        | Base URL of the Prometheus HTTP API                                  | `https://prometheus.your-domain.com` |
| **PROMETHEUS\_AUTH\_TYPE** | Authentication mode: `none`, `bearer`, or `basic`                    | `basic`                              |
| **PROMETHEUS\_TOKEN**      | Bearer token (Bearer Token mode only)                                | `eyJhbGci...`                        |
| **PROMETHEUS\_USERNAME**   | Username, or numeric instance ID for Grafana Cloud (Basic Auth only) | `1234567`                            |
| **PROMETHEUS\_PASSWORD**   | Password or access-policy token (Basic Auth only)                    | `glc_xxxxx...`                       |

***

## Required permissions

The Prometheus connector is **read-only** — agents query and inspect but never write to your monitoring backend.

* For **Grafana Cloud**, create an access-policy token with the **metrics:read** scope only.
* For protected endpoints, ensure the credentials can reach the query, labels, targets, rules, and alerts API paths.

<Tip>
  On Grafana Cloud, scope the access-policy token to `metrics:read` only — no other scope is needed for CloudThinker.
</Tip>

***

## Agent capabilities

The Prometheus connector is read-only — agents query and inspect, but never modify your monitoring backend.

| Capability            | What the agent can do                                                             |
| --------------------- | --------------------------------------------------------------------------------- |
| **Instant queries**   | Run a PromQL expression for a single point in time                                |
| **Range queries**     | Run a PromQL expression over a time window with a step interval                   |
| **Metric discovery**  | List available metric names, optionally filtered by prefix                        |
| **Label enumeration** | List label names and inspect the dimensions a metric is sliced by                 |
| **Target health**     | Inspect scrape targets and spot ones that are down or unhealthy                   |
| **Alert inspection**  | List active alerts and review configured alert rules                              |
| **Health probe**      | Run the universal `up` query to confirm the backend and its targets are reachable |

### Verify the connection

```text theme={null}
@alex run the Prometheus health probe and confirm all scrape targets are reachable
```

### Example prompts

```text theme={null}
@alex query node_cpu utilization across the cluster for the last hour and #report anything sustained above 85%
@kai list scrape targets that are currently down and #report which jobs they belong to
@alex show all active alerts and #recommend which to investigate first
```

<Note>
  Prometheus exposes no tool for label **values** — label enumeration returns label **names** only. Name the metric and the labels you care about so the agent can build an accurate PromQL selector.
</Note>

***

## Troubleshooting

<Accordion title="Connection or query fails with 401 Unauthorized">
  * Confirm **PROMETHEUS\_AUTH\_TYPE** matches what the endpoint expects.
  * For **Bearer**, verify the token is current and has not been revoked.
  * For **Basic**, verify the username/password — on Grafana Cloud, the username is the numeric instance ID and the password is the access-policy token.
</Accordion>

<Accordion title="Targets, rules, or alerts return 404">
  * Expected on managed, Mimir-backed endpoints (Grafana Cloud) — these paths are not exposed.
  * The query API (instant, range, labels, metadata) still works; use queries instead of target/rule inspection.
</Accordion>

<Accordion title="Connection fails to reach the endpoint">
  * Verify **PROMETHEUS\_URL** is reachable from CloudThinker over HTTPS.
  * For self-hosted or network-restricted endpoints, confirm there's a network path from CloudThinker.
  * Drop any trailing `/api/v1` from the URL — enter only the base URL.
</Accordion>

<Accordion title="A query returns empty results">
  * Confirm the metric exists with a discovery query before slicing by labels.
  * Widen the time window — the series may not have samples in the requested range.
</Accordion>

***

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Read-only by design** — the connector never writes to your monitoring backend; no write permissions are needed
- **Least-privilege credentials** — on Grafana Cloud, scope the access-policy token to metrics read only

***

## Related

<CardGroup cols={2}>
  <Card title="Grafana Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/grafana.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c1329049025cd3c3a0909b400baef7be" href="/guide/connections/grafana" width="24" height="24" data-path="images/icons/grafana.svg">
    Dashboards and unified observability
  </Card>

  <Card title="Datadog Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/datadog.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=e8382167f2a1eb1e00971b5f4d703d48" href="/guide/connections/datadog" width="24" height="24" data-path="images/icons/datadog.svg">
    Log search, metrics, and infrastructure monitoring
  </Card>
</CardGroup>