Grafana Cloud API
The Grafana Cloud API is sometimes referred to as the Grafana.com API or the Gcom API. It is a work in progress, however the following calls and paths on this page are static and approved for general use. If you hear of other paths and calls, know that they are subject to change and not generally maintained for user consumption.
Authentication
Generate an API token in the Grafana.com user portal at https://grafana.com/orgs/<org_slug>/api-keys
. Make sure it has the “Admin” role.
Requests to the API are authenticated using the Authorization header:
Authorization: Bearer <grafana.com API token>
API Keys
List API Keys
GET https://grafana.com/api/orgs/<org_slug>/api-keys
Create API Key
POST https://grafana.com/api/orgs/<org_slug>/api-keys
Body
name
(string) – API key name.role
(string) – Permission level of API key. One of “Viewer”, “Editor”, “Admin”, or “MetricsPublisher”.
Delete API Key
DELETE https://grafana.com/api/orgs/<org_slug>/api-keys/<api key name>
Stacks
List Stacks
GET https://grafana.com/api/orgs/<org_slug>/instances
Create Stack
Note: Grafana Cloud Free includes 1 stack and Grafana Cloud Pro includes up to 3 stacks. Reach out to us about Grafana Cloud Advanced if you would like to add additional stacks to your account.
POST https://grafana.com/api/instances
Body
-
name
(string) – Name of stack. Conventionally matches the url of the instance (e.g. “<stack_slug>.grafana.net”) -
slug
(string) – Subdomain that the Grafana instance will be available at (i.e. setting slug to “<stack_slug>” will make the instance available at “https://<stack_slug>.grafana.net”. -
url
(string, optional) – If a custom domain will be used for the instance it must be provided here. For example:“https://grafana.yourdoman.io”
. Note that the custom domain must have aCNAME
record set up that points to <stack_slug>.grafana.net before it can be specified. -
region
(string, optional) — Choose a region for your stack. For example, you can specify the United States:us
, or Europe:eu
.Use the
GET /api/stack-regions
endpoint to see a list of regions to choose from. For more information, see List regions.If you don’t specify a region, the default is
us
.
Delete Stack
DELETE https://grafana.com/api/instances/<stack_slug>
Restart Grafana
POST https://grafana.com/api/instances/<stack_slug>/restart
Create Hosted Grafana instance API keys
POST https://grafana.com/api/instances/<stack_slug>/api/auth/keys
This creates API keys specific to use for managing your hosted Grafana instance. This is different from Grafana Cloud API keys created for Grafana Cloud operations.
This endpoint requires the Admin role. See the Grafana docs for more details.
Body
name
(string) – Name of the API key.role
(string) – Access level/Grafana Role for the key. Can be one of the following values: Viewer, Editor or Admin.secondsToLive
(number, optional) – Key expiration in seconds. If it is a positive number an expiration date for the key is set. If it is null, zero or is omitted completely (unless api_key_max_seconds_to_live configuration option is set) the key will never expire.
Grafana Provisioned Data Sources
List Data Sources
GET https://grafana.com/api/instances/<stack_slug>/datasources
Grafana Plugins
The API allows managing plugins installed on your hosted Grafana instances.
You can discover plugins in the Grafana Plugins Directory.
List plugins installed on an instance
GET https://grafana.com/api/instances/<stack_slug>/plugins
Add a plugin to instance
POST https://grafana.com/api/instances/<stack_slug>/plugins
Body
plugin
(string) – Name of the plugin, e.g.grafana-github-datasource
.version
(string, optional) – Version of the plugin to install. Defaults to latest.
Get installed plugin info
GET https://grafana.com/api/instances/<stack_slug>/plugins/<plugin>
Update installed plugin version
POST https://grafana.com/api/instances/<stack_slug>/plugins/<plugin>
Body
version
(string) – New plugin version.
Delete an installed plugin
DELETE https://grafana.com/api/instances/<stack_slug>/plugins/<plugin>
Regions
List regions
Use the following call to retrieve a list of regions to specify when you create a stack.
GET https://grafana.com/api/stack-regions
Related Grafana Cloud resources
Intro to Prometheus and Grafana Cloud
Prometheus is taking over the monitoring world! In this webinar, we will start with a quick introduction to the open source project that’s the de facto standard for monitoring modern, cloud native systems.
How to set up and visualize synthetic monitoring at scale with Grafana Cloud
Learn how to use Kubernetes, Grafana Loki, and Grafana Cloud’s synthetic monitoring feature to set up your infrastructure's checks in this GrafanaCONline session.
Using Grafana Cloud to drive manufacturing plant efficiency
This GrafanaCONline session tells how Grafana helps a 75-year-old manufacturing company with product quality and equipment maintenance.