Registry / observability / grafana-client

grafana-client

JSON →
library5.1.0pypypiunverified

A client library for accessing the Grafana HTTP API, written in Python. It covers most available Grafana HTTP API endpoints and supports Grafana 5.x-9.x, with ongoing compatibility for newer versions, including Grafana 11. The library is actively maintained with a regular release cadence, supporting HTTP Basic authentication and token-based authentication.

pip install --upgrade grafana-client
INSTALL
IMPORT
SIG · GRAFANA-CLIENT
G
grafana-client
observabilitypythonv5.1.0
Install
3.3s avg
Import
913ms
Disk
37MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.956s · 38.6MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.3s · import 0.871s · 38MB
37MB installed
● package 37MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GrafanaApi
from grafana_client import GrafanaApi
AsyncGrafanaApi
from grafana_client import AsyncGrafanaApi
GrafanaAPI
from grafana_client import GrafanaApi
from grafana_api.grafana_api import GrafanaAPI
The 'grafana_api' package is an older, unmaintained library. 'grafana-client' is its spiritual successor. Ensure you are importing from 'grafana_client'.

This quickstart demonstrates how to connect to a Grafana instance using either an API token or HTTP Basic Authentication. It then retrieves the Grafana version and lists existing dashboards. Ensure `GRAFANA_URL` and `GRAFANA_TOKEN` environment variables are set. For API token, `GRAFANA_TOKEN` should be the token itself. For basic auth, it should be in `username:password` format.

import os from grafana_client import GrafanaApi GRAFANA_URL = os.environ.get('GRAFANA_URL', 'http://localhost:3000') GRAFANA_TOKEN = os.environ.get('GRAFANA_TOKEN', 'eyJrIjoiV1N...') # Or 'admin:admin' for basic auth # For API token authentication # grafana = GrafanaApi.from_url(f"{GRAFANA_URL}", token=GRAFANA_TOKEN) # For basic authentication (e.g., admin user) username, password = GRAFANA_TOKEN.split(':', 1) if ':' in GRAFANA_TOKEN else ('', '') if not username or not password: print("Warning: GRAFANA_TOKEN env var not set correctly for basic auth (e.g., 'admin:admin').") print("Trying with API token instead.") grafana = GrafanaApi.from_url(GRAFANA_URL, token=GRAFANA_TOKEN) else: grafana = GrafanaApi.from_url(GRAFANA_URL, basic_auth=(username, password)) try: # Get Grafana's current version (requires authentication since 5.0.0) version_info = grafana.version() print(f"Connected to Grafana version: {version_info.get('version')}") # Example: List all dashboards dashboards = grafana.search.search_dashboards() print(f"Found {len(dashboards)} dashboards.") if dashboards: print(f"First dashboard title: {dashboards[0].get('title')}") except Exception as e: print(f"An error occurred: {e}") print("Ensure GRAFANA_URL and GRAFANA_TOKEN are correctly set.")
Debug
Known issues
breakingVersion 5.0.0 introduced a breaking change: authentication is now *obligatory* for all API calls, as the library fetches the Grafana version from `/api/frontend/settings` instead of `/api/health`. The `/api/health` endpoint previously allowed unauthenticated access. Additionally, the 'database' status is no longer represented in the response.
fix
Ensure all GrafanaApi initializations include authentication credentials (e.g., `token` or `basic_auth`). If upgrading from a pre-5.0.0 version and calls were unauthenticated, they will now fail.
affects: >=5.0.0
breakingVersion 4.0.0 changed the underlying HTTP backend from `requests` to `niquests`. This primarily affects error handling, as `requests.exceptions.Timeout` exceptions are no longer propagated. Instead, `GrafanaTimeoutError` is used. Python 3.6 support was also dropped.
fix
Update exception handling blocks to catch `GrafanaTimeoutError` instead of `requests.exceptions.Timeout`. If using Python 3.6, upgrade to Python 3.7 or newer.
affects: >=4.0.0
gotchaInsufficient Grafana API Key Permissions: A common issue is providing an API key with inadequate permissions for the desired operations (e.g., a Viewer key trying to create dashboards). While the API might return a 200 OK, the operation may silently fail or return an empty result.
fix
Always generate Grafana API keys with the least privileged role necessary for your script's operations (e.g., Editor for dashboard management, Admin for user management). Double-check Grafana logs for permission-related errors if an API call seems to succeed but yields unexpected results.
affects: All
gotchaGrafana Organization Context with HTTP Basic Authentication: When using HTTP Basic Authentication, requests are made within the authenticated user's current organization context. This might lead to unexpected behavior if the user is part of multiple organizations and the desired organization is not active. API tokens are typically bound to a single organization.
fix
To ensure operations target a specific organization, use an API token (which is tied to one org) or explicitly switch the user's organization context using `GrafanaApi.user.switch_actual_user_organisation` after authentication. Alternatively, bind the `GrafanaApi` instance to a specific organization using `organization_id` parameter, which sends the `X-Grafana-Org-Id` header.
affects: All
Upgrade
Version history
5.1.0latest on PyPI · released Apr 22, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
47 hits · last 30 days
node
42
OpenAI (training)
2
Resources
grafana-client — pip install grafana-client · libregistry