Skip to main content

A client library for accessing the Grafana HTTP API, written in Python

Project description


Tests Test coverage License

Python versions Grafana versions

Status PyPI Downloads


A client library for accessing the Grafana HTTP API, written in Python.


Install the package from PyPI.

pip install grafana-client --upgrade


API overview

This section gives you an idea about how to use the API on behalf of a few samples.

from grafana_client import GrafanaApi

# Connect to Grafana API endpoint using the `GrafanaApi` class
grafana = GrafanaApi.from_url(

# Create user
user = grafana.admin.create_user({
    "name": "User", 
    "email": "", 
    "login": "user", 
    "password": "userpassword", 
    "OrgId": 1,

# Change user password
user = grafana.admin.change_user_password(2, "newpassword")

# Search dashboards based on tag"applications")

# Find a user by email
user = grafana.users.find_user("")

# Add user to team 2
grafana.teams.add_team_member(2, user["id"])

# Create or update a dashboard
    dashboard={"dashboard": {...}, "folderId": 0, "overwrite": True})

# Delete a dashboard by UID

# Create organization
    organization={"name": "new_organization"})

Or using asynchronous code... the interfaces are identical except for the fact that you will handle coroutines (async/await).

from grafana_client import AsyncGrafanaApi
import asyncio

async def main():
    # Connect to Grafana API endpoint using the `GrafanaApi` class
    grafana = AsyncGrafanaApi.from_url("")
    # Create user
    user = await grafana.admin.create_user({
        "name": "User", 
        "email": "", 
        "login": "user", 
        "password": "userpassword", 
        "OrgId": 1,
    # Change user password
    user = await grafana.admin.change_user_password(2, "newpassword")

Example programs

There are complete example programs to get you started within the examples folder of this repository.

Feel free to use them as blueprints for your own programs. If you think your exercises could be useful for others, don't hesitate to share them back.


There are several ways to authenticate to the Grafana HTTP API.

  1. Anonymous access
  2. Grafana API token
  3. HTTP Basic Authentication
  4. HTTP Header Authentication

The Grafana Admin API is a subset of the Grafana API. For accessing those API resources, you will need to use HTTP Basic Authentication.

from grafana_client import GrafanaApi, HeaderAuth, TokenAuth

# 1. Anonymous access
grafana = GrafanaApi.from_url(

# 2. Use Grafana API token.
grafana = GrafanaApi.from_url(

# 3. Use HTTP basic authentication.
grafana = GrafanaApi.from_url(
grafana = GrafanaApi.from_url(
    credential=("username", "password")

# 4. Use HTTP Header authentication.
grafana = GrafanaApi.from_url(
    credential=HeaderAuth(name="X-WEBAUTH-USER", value="foobar"),

# Optionally turn off TLS certificate verification.
grafana = GrafanaApi.from_url(

# Use `GRAFANA_URL` and `GRAFANA_TOKEN` environment variables.
grafana = GrafanaApi.from_env()

Please note that, on top of the specific examples above, the object obtained by credential can be an arbitrary niquests.auth.AuthBase instance.

Selecting Organizations

If the Grafana API is authenticated as a user (for example, with HTTP Basic Authentication), it will use the user's current organization context. That context can be changed with the GrafanaApi.user.switch_actual_user_organisation function.


An instance of GrafanaApi can also be bound to a single organization with the organization_id parameter, ensuring that all requests will be made to that organization. This parameter will cause GrafanaClient to use the X-Grafana-Org-Id header.

grafana = GrafanaApi(..., organization_id=1)

API Tokens are bound to a single organization, so the organization_id parameter does not need to be specified.

Timeout settings

The default timeout value is five seconds, used for both connect and read timeout.

The constructors of GrafanaApi and GrafanaClient, as well as the factory methods from_url and from_env accept the timeout argument, which can be obtained as a scalar float value, or as a tuple of (<read timeout>, <connect timeout>).


The underlying niquests library honors the HTTP_PROXY and HTTPS_PROXY environment variables. Setting them before invoking an application using grafana-client has been confirmed to work. For example:

export HTTP_PROXY=

DNS Resolver

niquests support using a custom DNS resolver, like but not limited, DNS-over-HTTPS, and DNS-over-QUIC. You will have to set NIQUESTS_DNS_URL environment variable. For example:

export NIQUESTS_DNS_URL="doh+cloudflare://"

See the documentation to learn more about accepted URL parameters and protocols.


This section of the documentation outlines which parts of the Grafana HTTP API are supported, and to which degree. See also Grafana HTTP API reference.


grafana-client is largely compatible with Grafana 5.x-10.x. However, earlier versions of Grafana might not support certain features or subsystems.


API Status
Admin +
Alerting +-
Alerting Notification Channels +
Alerting Provisioning +
Annotations +
Authentication +-
Dashboard +
Dashboard Versions +
Dashboard Permissions +
Data Source +
Data Source Permissions +
External Group Sync +
Folder +
Folder Permissions +
Folder/Dashboard Search +-
Health +
Library Elements +
Organisation +
Other +
Plugin +
Preferences +
Rbac +-
Snapshot +
Teams +
User +

Data source health check


For checking whether a Grafana data source is healthy, Grafana 9 and newer has a server-side data source health check API. For earlier versions, a client-side implementation is provided.

This implementation works in the same manner as the "Save & test" button works, when creating a data source in the user interface.

The feature can be explored through corresponding client programs in the examples folder of this repository.


The minimum required version for data source health checks is Grafana 7. Prometheus only works on Grafana 8 and newer.

Data source coverage

Health checks are supported for these Grafana data source types.

  • CrateDB
  • Elasticsearch
  • Graphite
  • InfluxDB
  • Jaeger
  • Loki
  • Microsoft SQL Server
  • OpenTSDB
  • PostgreSQL
  • Prometheus
  • Tempo
  • Testdata
  • Zipkin

We are humbly asking the community to contribute adapters for other data source types, popular or not.


A list of applications based on grafana-client.

Project information


The library was originally conceived by Andrew Prokhorenkov and contributors as grafana_api. Thank you very much for your efforts!

At future maintenance of grafana_api, we discussed the need for a fork because the repository stopped receiving updates since more than a year. While forking it, we renamed the package to grafana-client and slightly trimmed the module namespace.


Thanks to the original authors and all contributors who helped to co-create and conceive this software in one way or another. You know who you are.


Any kind of contribution and feedback are very much welcome! Just create an issue or submit a patch if you think we should include a new feature, or to report or fix a bug.

The issue tracker URL is:


In order to set up a development environment for grafana-client, please follow the development documentation.


grafana-client is licensed under the terms of the MIT License, see LICENSE file.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

grafana_client-4.1.0.tar.gz (105.6 kB view hashes)

Uploaded Source

Built Distribution

grafana_client-4.1.0-py3-none-any.whl (103.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page