Grafana HTTP API

Everything you click in the Grafana interface exists as an API call too. The HTTP API lets scripts and tools create dashboards, add users, read data sources, and mark events on charts. Automation through the API saves hours of repeated clicking and keeps large setups consistent.

The Phone Order Analogy

You can walk into a restaurant and order at the counter, or you can phone in the same order. The kitchen prepares the same dish either way. Think of the interface as the counter and the API as the phone line. Both reach the same kitchen, so anything you do in one place appears in the other.

Browser (clicks)  ---+
                     +-->  Grafana  -->  Dashboards, users, alerts
Script (API calls) --+

Anatomy of an API Call

Part	Sample	Meaning
Method	GET	Read data. POST creates, PUT or PATCH updates, DELETE removes.
Address	http://localhost:3000/api/search	The server and the endpoint
Header	Authorization: Bearer TOKEN	Proof of identity
Body	{"title": "New Folder"}	Data for create and update calls

Authenticate

Create a service account with the lowest role that fits the job, and generate a token. Send the token in the Authorization header with the word Bearer in front. Keep the token out of scripts that you share. Load it from an environment variable.

export GRAFANA_TOKEN="paste-token-here"

Check Server Health

The health endpoint needs no token. Monitoring tools use it to confirm that Grafana runs.

curl http://localhost:3000/api/health

{
  "database": "ok",
  "version": "11.0.0"
}

Search Dashboards

curl -H "Authorization: Bearer $GRAFANA_TOKEN" \
  "http://localhost:3000/api/search?query=web&type=dash-db"

The response lists matching dashboards with their titles, their unique IDs called UIDs, and their folders. Every other call identifies a dashboard by that UID.

Read One Dashboard

curl -H "Authorization: Bearer $GRAFANA_TOKEN" \
  "http://localhost:3000/api/dashboards/uid/abc123"

The answer contains the full JSON model of the dashboard and a metadata block. Read the JSON model topic for a detailed look at the structure.

Create a Folder

curl -X POST \
  -H "Authorization: Bearer $GRAFANA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Payments"}' \
  http://localhost:3000/api/folders

Create or Update a Dashboard

Send the dashboard JSON inside a wrapper object.

curl -X POST \
  -H "Authorization: Bearer $GRAFANA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboard": {
      "id": null,
      "uid": null,
      "title": "API Sample",
      "panels": []
    },
    "folderUid": "",
    "overwrite": false
  }' \
  http://localhost:3000/api/dashboards/db

Set id to null for a new dashboard. Grafana returns the new UID and the page address. Set overwrite to true when you want to replace an existing dashboard that has the same UID.

List Data Sources

curl -H "Authorization: Bearer $GRAFANA_TOKEN" \
  http://localhost:3000/api/datasources

Use the API From Python

import os
import requests

base = "http://localhost:3000"
headers = {"Authorization": "Bearer " + os.environ["GRAFANA_TOKEN"]}

reply = requests.get(base + "/api/search?type=dash-db", headers=headers)
reply.raise_for_status()

for item in reply.json():
    print(item["title"], item["uid"])

The script prints every dashboard title with its UID. Extend it to download each dashboard and save the JSON, and you have a simple backup tool.

Response Codes

Code	Meaning	Typical Fix
200	Success	None
400	Bad request body	Check the JSON structure
401	Missing or invalid token	Check the header and the token
403	Token lacks permission	Raise the role or adjust folder permissions
404	Item not found	Check the UID or the address
412	Version conflict	Reload the dashboard and retry

Common Automation Jobs

Job	Endpoint Family	Benefit
Nightly dashboard export	/api/search and /api/dashboards/uid	Version-controlled copies of every dashboard
Create folders and permissions for a new team	/api/folders	Consistent setup in seconds
Mark releases on charts	/api/annotations	Spikes get an explanation
Register data sources after a rebuild	/api/datasources	Repeatable environments

Pagination and Limits

Search results arrive in pages. Add the limit and page parameters when your server holds hundreds of dashboards, and loop until the response comes back empty. Rate limits may apply on shared or cloud servers, so pause briefly between calls and retry politely after an error.

Explore the Reference

Grafana documents every endpoint with sample requests and responses. Check the page that matches your server version before you write a script, because fields and paths evolve between releases. Try each call in a terminal first, read the response, and move the working call into your script.

Habits for Safe Automation

• Test scripts against a test server before production.
• Give each script its own service account and token.
• Pause between calls in loops to avoid overloading the server.
• Log every change a script makes.
• Read the API reference for your Grafana version, because endpoints evolve.