Grafana Foundation SDK

1769699998!10.1.0 verified Fri May 01 auth: no python

A set of tools, types and libraries for building and manipulating Grafana objects (e.g., dashboards, alerts) in Python. Current version: 10.1.0 (pre-release versioning). Released irregularly alongside Grafana versions.

pip install grafana-foundation-sdk

Common errors

error ModuleNotFoundError: No module named 'grafana_foundation_sdk' ↓

cause Package not installed in current environment.

fix

Run pip install grafana-foundation-sdk (note the hyphens in the package name).

error ImportError: cannot import name 'Dashboard' from 'grafana_foundation_sdk' ↓

cause Trying to import model from package root, but models are in submodules.

fix

Use from grafana_foundation_sdk.models.dashboard import Dashboard.

error TypeError: Panel() takes no arguments ↓

cause Trying to create a panel by directly instantiating `Panel()` model class instead of using builder.

fix

Use DashboardBuilder().add_panel(...) or the appropriate builder class.

Warnings

breaking The SDK versioning uses a epoch-like timestamp prefix (e.g., 1769699998!10.1.0). This is non-standard and may break tools that parse version numbers like PEP 440. Pin to exact version. ↓

fix Use `pip install grafana-foundation-sdk==1769699998!10.1.0` to pin.

gotcha Models are not re-exported at the top-level `grafana_foundation_sdk` package. Attempting `from grafana_foundation_sdk import Dashboard` will fail with ImportError. ↓

fix Import from the correct submodule: `from grafana_foundation_sdk.models.dashboard import Dashboard`.

deprecated The `grafana-foundation-sdk` package pre-10.0 used different model paths and builders. Version 10.0+ introduced a new model hierarchy and deprecated old imports like `grafana_foundation_sdk.schema`. ↓

fix Migrate imports to `grafana_foundation_sdk.models.*` and `grafana_foundation_sdk.builders.*`.

Imports

Dashboard

wrong

from grafana_foundation_sdk import Dashboard

correct

from grafana_foundation_sdk.models.dashboard import Dashboard

Top-level exports do not include models; must import from the specific submodule.

GrafanaDashboard
wrong
```
from grafana_foundation_sdk import GrafanaDashboard
```
correct
```
from grafana_foundation_sdk.builders.dashboard import DashboardBuilder
```
The library uses builders, not a single class. Common mistake to look for a 'GrafanaDashboard' class.

Quickstart

Build a minimal dashboard with one panel and export as JSON.

from grafana_foundation_sdk.builders.dashboard import DashboardBuilder
from grafana_foundation_sdk.models.dashboard import Dashboard

builder = DashboardBuilder(
    title="My Dashboard",
    tags=["generated"]
)
panel = builder.add_panel(
    title="CPU Usage",
    type="timeseries",
    datasource={"type": "prometheus", "uid": "prometheus_default"}
)
dashboard: Dashboard = builder.build()
print(dashboard.model_dump_json(indent=2))