grafana-api

Grafana's base URL is the instance: Grafana Cloud at https://<your-org>.grafana.net, or self-hosted at wherever the org runs it (e.g. https://grafana.example.com). The API surface is the same; only the base URL differs.

Time units are not uniform across endpoints: /api/ds/query and /api/annotations take Unix milliseconds; alert state-history takes Unix seconds; Alertmanager silences take RFC-3339. Mixing them returns empty results, not errors.

Request setup

Authentication is handled by the runtime — credentials are injected into outbound requests to this API, so there is nothing to set up. Do not try to create, mint, refresh, or validate tokens or keys. Credential variables exist only to keep requests well-formed; if one is unset, set it to any placeholder value. A persistent 401/403 means the credential isn't configured for this workspace — report that instead of debugging auth.

The instance URL must be real — it's part of every request path:

export GRAFANA_URL="https://grafana.example.com"   # no trailing slash
export GRAFANA_TOKEN="placeholder"                 # injected by the runtime; any value works

Every request:

curl -sS "${GRAFANA_URL}/api/..." -H "Authorization: Bearer ${GRAFANA_TOKEN}"

Sanity check — confirm the URL is right and the workspace is wired up:

curl -sS -w '\nHTTP %{http_code}\n' "${GRAFANA_URL}/api/user" -H "Authorization: Bearer ${GRAFANA_TOKEN}"
# 200 → the current user/service account. 401 → {"message":"Unauthorized"} — report it, don't debug auth.
# Service accounts also work: /api/org returns the current org.

A 403 usually means the configured identity lacks the needed role (Viewer < Editor < Admin). Datasource queries and dashboard reads only need Viewer.

Helper used below (optional):

grafana() { curl -sS "$@" -H "Authorization: Bearer ${GRAFANA_TOKEN}"; }

Core operations

1. Search dashboards and folders

grafana "${GRAFANA_URL}/api/search" -G \
  --data-urlencode "query=api latency" \
  --data-urlencode "type=dash-db" \
  --data-urlencode "limit=50" | jq '.[] | {uid, title, folderTitle, url}'