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}'

type is dash-db (dashboards) or dash-folder (folders); omit it for both. Also: tag=,

folderUIDs=, starred=true.

2. Get a dashboard by UID

The UID is the short string in the dashboard URL: .../d/<uid>/<slug>.

grafana "${GRAFANA_URL}/api/dashboards/uid/abc123xy" | \
  jq '{title: .dashboard.title, folder: .meta.folderTitle, panels: [.dashboard.panels[]? | {id, title, type}]}'

Each panel's PromQL/LogQL/SQL is under .dashboard.panels[].targets. A bad UID returns

{"message":"Dashboard not found"} (404).

3. Run a datasource query

This is how you ask the same questions a panel asks. First find the datasource UID:

grafana "${GRAFANA_URL}/api/datasources" | jq '.[] | {uid, name, type}'

Then POST to /api/ds/query. The queries[] shape depends on the datasource type; this is a

Prometheus example:

NOW_MS=$(( $(date +%s) * 1000 )); FROM_MS=$(( NOW_MS - 3600000 ))
grafana -X POST "${GRAFANA_URL}/api/ds/query" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "'"${FROM_MS}"'",
    "to": "'"${NOW_MS}"'",
    "queries": [{
      "refId": "A",
      "datasource": {"uid": "<datasource_uid>"},
      "expr": "sum(rate(http_requests_total{job=\"api\"}[5m])) by (status)",
      "intervalMs": 30000,
      "maxDataPoints": 500
    }]
  }' | jq '.results.A.error // .results.A.frames[0].data.values'

For Loki, use "expr": "{job=\"api\"} |= \"error\"" and optionally "queryType": "range". For SQL

datasources, use "rawSql": "SELECT ..." and "format": "table".

Responses are Grafana data frames: results.<refId>.frames[] with parallel column arrays in

data.values and column metadata in schema.fields. **On a datasource-side failure frames is

empty and the error from Prometheus/Loki/SQL is embedded in results.<refId>.error** — the HTTP

status may still be 200 or 500, so check that field rather than relying on status alone.

4. List alert rules

Two surfaces with different jobs:

# live STATE (firing/pending/inactive) — read-only
grafana "${GRAFANA_URL}/api/prometheus/grafana/api/v1/rules" | \
  jq '.data.groups[]? | {folder: .file, group: .name, rules: [.rules[] | {name, state, health}]}'

# DEFINITIONS (query, condition, labels, for-duration) — full CRUD, no runtime state
grafana "${GRAFANA_URL}/api/v1/provisioning/alert-rules" | jq '.[] | {uid, title, folderUID, condition}'

The grafana segment in the first path is the literal {am_name} for the built-in Alertmanager;

external Alertmanagers use their datasource UID. Resources written via the provisioning API are

locked in the UI unless you send X-Disable-Provenance: true on the write.

5. Silences

startsAt/endsAt are RFC-3339 (date -u +%Y-%m-%dT%H:%M:%SZ).

# active silences
grafana "${GRAFANA_URL}/api/alertmanager/grafana/api/v2/silences" | \
  jq '.[] | select(.status.state=="active") | {id, comment, matchers, endsAt}'

# create a 2-hour silence matching a label
# GNU date; on BSD/macOS use: date -u -v+2H +%Y-%m-%dT%H:%M:%SZ
START=$(date -u +%Y-%m-%dT%H:%M:%SZ)
END=$(date -u -d "+2 hours" +%Y-%m-%dT%H:%M:%SZ)
grafana -X POST "${GRAFANA_URL}/api/alertmanager/grafana/api/v2/silences" \
  -H "Content-Type: application/json" \
  -d '{
    "matchers": [{"name": "alertname", "value": "HighErrorRate", "isRegex": false, "isEqual": true}],
    "startsAt": "'"${START}"'", "endsAt": "'"${END}"'",
    "createdBy": "api", "comment": "investigating"
  }'
# success → {"silenceID": "..."}

# expire a silence
grafana -X DELETE "${GRAFANA_URL}/api/alertmanager/grafana/api/v2/silence/<silence_id>"

6. Annotations

time/timeEnd are Unix milliseconds.

grafana -X POST "${GRAFANA_URL}/api/annotations" -H "Content-Type: application/json" \
  -d '{"time": '"$(( $(date +%s) * 1000 ))"', "tags": ["deploy","api"], "text": "Deployed v2.3.1"}'

grafana "${GRAFANA_URL}/api/annotations?from=${FROM_MS}&to=${NOW_MS}&tags=deploy" | jq .

7. Folders

grafana "${GRAFANA_URL}/api/folders" | jq '.[] | {uid, title}'
grafana -X POST "${GRAFANA_URL}/api/folders" -H "Content-Type: application/json" -d '{"title": "Team API"}'

8. Create or update a dashboard

grafana -X POST "${GRAFANA_URL}/api/dashboards/db" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboard": {"uid": null, "title": "My Dashboard", "panels": [], "schemaVersion": 41},
    "folderUid": "<folder_uid>",
    "overwrite": false,
    "message": "created via API"
  }'

To update: GET the dashboard first and send the whole JSON back with your change applied —

this endpoint replaces the dashboard. Set dashboard.uid to the existing UID and either include the

current dashboard.version (Grafana returns 412 on mismatch) or set overwrite: true.

Pagination

/api/search and /api/folders use limit + page query params (1-indexed). /api/search

defaults to 1000 and caps at 5000. /api/annotations has limit (default 100) but no page —

narrow the from/to window instead. Alertmanager endpoints are not paginated. When you hit a cap,

narrow with query=, tag=, or folderUIDs= instead of paging through everything.

Rate limits

Self-hosted Grafana has no built-in per-token rate limits by default. Grafana Cloud may return

429 on heavy API or query traffic — limits vary by plan and endpoint, so honor Retry-After

if present, otherwise back off.

/api/ds/query is the expensive path: each call fans out to the underlying database, so batch

multiple queries[] into one request instead of looping.

Error handling

Error bodies always carry "message" (sometimes "messageId"/"traceID"). Service-specific cases:

• 412 — Version conflict on dashboard save. GET the latest, reapply your change, include version, or set overwrite: true.
• 200/500 on /api/ds/query — Datasource-side failure. The Prometheus/Loki/SQL error is embedded in results.<refId>.error; frames is empty.
• 403 — Insufficient role. Viewer < Editor < Admin; folder-level permissions also apply.

401 → credential not configured for this workspace (report, don't debug). UIDs are case-sensitive

short strings, not titles.

Going deeper

references/api.md has the full endpoint catalog — dashboards, folders, datasources, ds/query

per-datasource shapes, the full unified-alerting surface (alert rules, contact points, notification

policies, mute timings, Alertmanager), annotations, snapshots, orgs/users/teams, service accounts,

and short URLs. Read it when you need an endpoint beyond the ones above.