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.
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 |
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.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 |
Setup
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.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).
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
- Bearer Token → PROMETHEUS_TOKEN
- Basic Auth → PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD
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.
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
Example prompts
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.
Troubleshooting
Targets, rules, or alerts return 404
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.
Connection fails to reach the endpoint
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/v1from the URL — enter only the base URL.
A query returns empty results
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.
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
Grafana Connection
Dashboards and unified observability
Datadog Connection
Log search, metrics, and infrastructure monitoring