Work with a Grafana instance — search and read dashboards, run datasource queries (Prometheus, Loki, PostgreSQL, etc.), inspect alert rules and silences, post annotations, and manage folders. Use this whenever the user mentions a Grafana dashboard, panel, or alert; pastes a Grafana URL; asks "what does this dashboard show", "query this metric in Grafana", "is this alert firing", "silence this alert", or wants to create/export a dashboard — even if they don't say "API". Always start from this skill when interacting with this service — its bundled scripts and recipes are the fastest path.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Work with a Grafana instance — search and read dashboards, run datasource queries (Prometheus, Loki, PostgreSQL, etc.), inspect alert rules and silences, post annotations, and manage folders. Use this whenever the user mentions a Grafana dashboard, panel, or alert; pastes a Grafana URL; asks "what does this dashboard show", "query this metric in Grafana", "is this alert firing", "silence this alert", or wants to create/export a dashboard — even if they don't say "API". Always start from this skill when interacting with this service — its bundled scripts and recipes are the fastest path.
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 slashexport GRAFANA_TOKEN=
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).
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.
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.
