{"id":21890633,"url":"https://github.com/grafana-toolbox/grafana-client","last_synced_at":"2026-02-15T13:18:44.198Z","repository":{"id":37010453,"uuid":"454560833","full_name":"grafana-toolbox/grafana-client","owner":"grafana-toolbox","description":"Python client library for accessing the Grafana HTTP API.","archived":false,"fork":false,"pushed_at":"2026-02-04T14:20:27.000Z","size":685,"stargazers_count":136,"open_issues_count":11,"forks_count":40,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-05T01:37:46.143Z","etag":null,"topics":["grafana","grafana-api","grafana-automation","grafana-client","grafana-data","grafana-datasource","grafana-explore","grafana-installation","grafana-interface","grafana-scripts","grafana-toolbox","grafana-utils","http-api","http-client","kotori-daq"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grafana-toolbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-02-01T21:43:08.000Z","updated_at":"2026-02-04T14:22:42.000Z","dependencies_parsed_at":"2023-10-16T13:54:34.237Z","dependency_job_id":"d063f8b6-47d0-491f-ae3b-74c79e15f1b7","html_url":"https://github.com/grafana-toolbox/grafana-client","commit_stats":{"total_commits":595,"total_committers":53,"mean_commits":"11.226415094339623","dds":0.6521008403361345,"last_synced_commit":"c6c799bf30d43d74b1d0d07d4f14716122092a37"},"previous_names":["grafana-toolbox/grafana-client","panodata/grafana-client"],"tags_count":117,"template":false,"template_full_name":null,"purl":"pkg:github/grafana-toolbox/grafana-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana-toolbox%2Fgrafana-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana-toolbox%2Fgrafana-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana-toolbox%2Fgrafana-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana-toolbox%2Fgrafana-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grafana-toolbox","download_url":"https://codeload.github.com/grafana-toolbox/grafana-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana-toolbox%2Fgrafana-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29479464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T11:35:25.641Z","status":"ssl_error","status_checked_at":"2026-02-15T11:34:57.128Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grafana","grafana-api","grafana-automation","grafana-client","grafana-data","grafana-datasource","grafana-explore","grafana-installation","grafana-interface","grafana-scripts","grafana-toolbox","grafana-utils","http-api","http-client","kotori-daq"],"created_at":"2024-11-28T12:16:11.001Z","updated_at":"2026-02-15T13:18:44.192Z","avatar_url":"https://github.com/grafana-toolbox.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# grafana-client\n\n[![Tests](https://github.com/grafana-toolbox/grafana-client/workflows/Test/badge.svg)](https://github.com/grafana-toolbox/grafana-client/actions?query=workflow%3ATest)\n[![Test coverage](https://img.shields.io/codecov/c/gh/grafana-toolbox/grafana-client.svg?style=flat-square)](https://codecov.io/gh/grafana-toolbox/grafana-client/)\n[![License](https://img.shields.io/github/license/grafana-toolbox/grafana-client.svg?style=flat-square)](https://github.com/grafana-toolbox/grafana-client/blob/main/LICENSE)\n\n[![Python versions](https://img.shields.io/pypi/pyversions/grafana-client.svg?style=flat-square)](https://pypi.org/project/grafana-client/)\n[![Grafana versions](https://img.shields.io/badge/Grafana-5.x%20--%2012.x-blue.svg?style=flat-square)](https://github.com/grafana/grafana)\n\n[![Status](https://img.shields.io/pypi/status/grafana-client.svg?style=flat-square)](https://pypi.org/project/grafana-client/)\n[![PyPI](https://img.shields.io/pypi/v/grafana-client.svg?style=flat-square)](https://pypi.org/project/grafana-client/)\n[![Downloads](https://img.shields.io/pypi/dm/grafana-client.svg?style=flat-square)](https://pypi.org/project/grafana-client/)\n\u003c!-- [![Conda](https://img.shields.io/conda/v/grafana-toolbox/grafana-client.svg?style=flat-square)](https://anaconda.org/grafana-toolbox/grafana-client) --\u003e\n\n\n## About\n\nA client library for accessing the Grafana HTTP API, written in Python.\n\n\n## Setup\n\nInstall the package from PyPI.\n```\npip install --upgrade grafana-client\n```\n\n\n## Usage\n\n### API overview\n\nThis section gives you an idea about how to use the API on behalf of a few\nsamples.\n\n#### Synchronous\n```python\nfrom grafana_client import GrafanaApi\n\n# Connect to Grafana API endpoint using the `GrafanaApi` class\ngrafana = GrafanaApi.from_url(\n    \"https://username:password@daq.example.org/grafana/\")\n\n# Create user\nuser = grafana.admin.create_user({\n    \"name\": \"User\",\n    \"email\": \"user@example.org\",\n    \"login\": \"user\",\n    \"password\": \"userpassword\",\n    \"OrgId\": 1,\n})\n\n# Change user password\nuser = grafana.admin.change_user_password(2, \"newpassword\")\n\n# Search dashboards based on tag\ngrafana.search.search_dashboards(tag=\"applications\")\n\n# Find a user by email\nuser = grafana.users.find_user(\"test@example.org\")\n\n# Add user to team 2\ngrafana.teams.add_team_member(2, user[\"id\"])\n\n# Create or update a dashboard\ngrafana.dashboard.update_dashboard(\n    dashboard={\"dashboard\": {...}, \"folderId\": 0, \"overwrite\": True})\n\n# Delete a dashboard by UID\ngrafana.dashboard.delete_dashboard(dashboard_uid=\"foobar\")\n\n# Create organization\ngrafana.organization.create_organization(\n    organization={\"name\": \"new_organization\"})\n```\n\n#### Asynchronous\n\nThe asynchronous interfaces are identical, except for the fact that you will\nneed to properly handle coroutines (async/await).\n\n```python\nimport asyncio\nfrom grafana_client import AsyncGrafanaApi\n\nasync def main():\n    # Connect to Grafana API endpoint using the `GrafanaApi` class\n    grafana = AsyncGrafanaApi.from_url(\"https://username:password@daq.example.org/grafana/\")\n\n    # Create user\n    user = await grafana.admin.create_user({\n        \"name\": \"User\",\n        \"email\": \"user@example.org\",\n        \"login\": \"user\",\n        \"password\": \"userpassword\",\n        \"OrgId\": 1,\n    })\n\n    # Change user password\n    user = await grafana.admin.change_user_password(2, \"newpassword\")\n\nasyncio.run(main())\n```\n\n### Example programs\n\nThere are complete example programs to get you started within the [examples\nfolder] of this repository.\n\nFeel free to use them as blueprints for your own programs. If you think your\nexercises could be useful for others, don't hesitate to share them back.\n\n\n## Configuration Settings\n\n### Authentication\n\nThere are several ways to authenticate to the Grafana HTTP API.\n\n1. Anonymous access\n2. Grafana API token\n3. HTTP Basic Authentication\n4. HTTP Header Authentication\n\nThe [Grafana Admin API] is a subset of the Grafana API. For accessing those API\nresources, you will need to use HTTP Basic Authentication.\n\n```python\nfrom grafana_client import GrafanaApi, HeaderAuth, TokenAuth\n\n# 1. Anonymous access\ngrafana = GrafanaApi.from_url(\n    url=\"https://daq.example.org/grafana/\",\n)\n\n# 2. Use Grafana API token.\ngrafana = GrafanaApi.from_url(\n    url=\"https://daq.example.org/grafana/\",\n    credential=TokenAuth(token=\"eyJrIjoiWHg...dGJpZCI6MX0=\"),\n)\n\n# 3. Use HTTP basic authentication.\ngrafana = GrafanaApi.from_url(\n    url=\"https://username:password@daq.example.org/grafana/\",\n)\ngrafana = GrafanaApi.from_url(\n    url=\"https://daq.example.org/grafana/\",\n    credential=(\"username\", \"password\")\n)\n\n# 4. Use HTTP Header authentication.\ngrafana = GrafanaApi.from_url(\n    url=\"https://daq.example.org/grafana/\",\n    credential=HeaderAuth(name=\"X-WEBAUTH-USER\", value=\"foobar\"),\n)\n\n# Optionally turn off TLS certificate verification.\ngrafana = GrafanaApi.from_url(\n    url=\"https://username:password@daq.example.org/grafana/?verify=false\",\n)\n\n# Use `GRAFANA_URL` and `GRAFANA_TOKEN` environment variables.\ngrafana = GrafanaApi.from_env()\n```\n\nPlease note that, on top of the specific examples above, the object obtained by\n`credential` can be an arbitrary `niquests.auth.AuthBase` instance.\n\n### DNS Resolver\n\n`niquests` support using a custom DNS resolver, like but not limited, DNS-over-HTTPS, and DNS-over-QUIC.\nYou will have to set `NIQUESTS_DNS_URL` environment variable. For example:\n```\nexport NIQUESTS_DNS_URL=\"doh+cloudflare://\"\n```\n\nSee the [documentation](https://niquests.readthedocs.io/en/latest/user/quickstart.html#set-dns-via-environment) to learn\nmore about accepted URL parameters and protocols.\n\n### Grafana Organization\n\nIf the Grafana API is authenticated as a user (for example, with HTTP Basic Authentication),\nit will use the user's current organization context.\nThat context can be changed with the `GrafanaApi.user.switch_actual_user_organisation` function.\n\n```python\ngrafana.user.switch_actual_user_organisation(1)\n```\n\nAn instance of `GrafanaApi` can also be bound to a single organization with the `organization_id` parameter,\nensuring that all requests will be made to that organization.\nThis parameter will cause `GrafanaClient` to use the [X-Grafana-Org-Id header].\n\n```python\ngrafana = GrafanaApi(..., organization_id=1)\n```\n\nAPI Tokens are bound to a single organization, so the `organization_id` parameter does not need to be specified.\n\n### HTTP Proxy\n\nThe underlying `niquests` library honors the `HTTP_PROXY` and `HTTPS_PROXY`\nenvironment variables. Setting them before invoking an application using\n`grafana-client` has been confirmed to work. For example:\n```\nexport HTTP_PROXY=10.10.1.10:3128\nexport HTTPS_PROXY=10.10.1.11:1080\n```\n\n### Pool Size\n\nBy default a session pool size of 10 is used. This can be changed by passing\nthe `session_pool_size` argument to the `GrafanaApi` constructor:\n```python\ngrafana.client.session_pool_size = 32\n```\n\n### TCP Timeout\n\nThe default timeout value is five seconds, used for both connect and read timeout.\n\nThe constructors of `GrafanaApi` and `GrafanaClient`, as well as the factory methods\n`from_url` and `from_env` accept the `timeout` argument, which can be obtained as a\nscalar `float` value, or as a tuple of `(\u003cread timeout\u003e, \u003cconnect timeout\u003e)`.\n\n\n## Details\n\nThis section of the documentation outlines which parts of the Grafana HTTP API\nare supported, and to which degree. See also [Grafana HTTP API reference].\n\n### Compatibility\n\n`grafana-client` is largely compatible with Grafana 5.x-10.x. However, earlier\nversions of Grafana might not support certain features or subsystems.\n\n### Overview\n\n| API | Status |\n|---|---|\n| Admin | + |\n| Alerting | +- |\n| Alerting Notification Channels | + |\n| Alerting Provisioning | + |\n| Annotations | + |\n| Authentication | +- |\n| Dashboard | + |\n| Dashboard Versions | + |\n| Dashboard Permissions | + |\n| Data Source | + |\n| Data Source Permissions | + |\n| External Group Sync | + |\n| Folder | + |\n| Folder Permissions | + |\n| Folder/Dashboard Search | +- |\n| Health | + |\n| Library Elements | + |\n| Organisation | + |\n| Other | + |\n| Plugin | + |\n| Preferences | + |\n| Rbac | +- |\n| Snapshot | + |\n| Teams | + |\n| User | + |\n\n\n### Data source health check\n\n#### Introduction\n\nFor checking whether a Grafana data source is healthy, Grafana 9 and newer has\na server-side data source health check API. For earlier versions, a client-side\nimplementation is provided.\n\nThis implementation works in the same manner as the \"Save \u0026 test\" button works,\nwhen creating a data source in the user interface.\n\nThe feature can be explored through corresponding client programs in the\n[examples folder] of this repository.\n\n#### Compatibility\n\nThe minimum required version for data source health checks is Grafana 7.\nPrometheus only works on Grafana 8 and newer.\n\n#### Data source coverage\n\nHealth checks are supported for these Grafana data source types.\n\n- CrateDB\n- Elasticsearch\n- Graphite\n- InfluxDB\n- Jaeger\n- Loki\n- Microsoft SQL Server\n- OpenTSDB\n- PostgreSQL\n- Prometheus\n- Tempo\n- Testdata\n- Zipkin\n\nWe are humbly asking the community to contribute adapters for other data\nsource types, popular or not.\n\n\n## Applications\n\nA list of applications based on `grafana-client`.\n\n- [grafana-import-tool](https://github.com/peekjef72/grafana-import-tool)\n- [grafana-ldap-sync-script](https://github.com/NovatecConsulting/grafana-ldap-sync-script)\n- [grafana-snapshots-tool](https://github.com/peekjef72/grafana-snapshots-tool)\n- [grafana-wtf](https://github.com/grafana-toolbox/grafana-wtf)\n- [nixops-grafana](https://github.com/tewfik-ghariani/nixops-grafana)\n\n\n## Project information\n\n### History\n\nThe library was originally conceived by [Andrew Prokhorenkov] and contributors\nas [grafana_api]. Thank you very much for your efforts!\n\nAt [future maintenance of `grafana_api`], we discussed the need for a fork\nbecause the repository stopped receiving updates since more than a year.\nWhile forking it, we renamed the package to `grafana-client` and slightly\ntrimmed the module namespace.\n\n\n### Acknowledgements\n\nThanks to the original authors and all [contributors] who helped to co-create\nand conceive this software in one way or another. You know who you are.\n\n\n### Contributing\n\nAny kind of contribution and feedback are very much welcome! Just create an\nissue or submit a patch if you think we should include a new feature, or to\nreport or fix a bug.\n\nThe issue tracker URL is: https://github.com/grafana-toolbox/grafana-client/issues\n\n\n### Development\n\nIn order to set up a development environment for `grafana-client`, please\nfollow the [development documentation].\n\n\n### License\n\n`grafana-client` is licensed under the terms of the MIT License, see [LICENSE] file.\n\n### Supported by\n\n[![JetBrains logo.](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSourceSupport)\n\nSpecial thanks to the people at JetBrains s.r.o. for supporting us with\nexcellent development tooling.\n\n\n[Andrew Prokhorenkov]: https://github.com/m0nhawk/grafana_api\n[contributors]: https://github.com/grafana-toolbox/grafana-client/graphs/contributors\n[development documentation]: https://github.com/grafana-toolbox/grafana-client/blob/main/docs/development.md\n[examples folder]: https://github.com/grafana-toolbox/grafana-client/tree/main/examples\n[future maintenance of `grafana_api`]: https://github.com/m0nhawk/grafana_api/issues/88\n[grafana_api]: https://github.com/m0nhawk/grafana_api\n[Grafana Admin API]: https://grafana.com/docs/grafana/latest/http_api/admin/\n[X-Grafana-Org-Id header]: https://grafana.com/docs/grafana/latest/developers/http_api/auth/#x-grafana-org-id-header\n[Grafana HTTP API reference]: https://grafana.com/docs/grafana/latest/http_api/\n[LICENSE]: https://github.com/grafana-toolbox/grafana-client/blob/main/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana-toolbox%2Fgrafana-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrafana-toolbox%2Fgrafana-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana-toolbox%2Fgrafana-client/lists"}