Grafana Cloud API

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

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
403	Forbidden.

Example response:

{
    "items": [
        {
            "id": 5045812,
            "orgId": 652945,
            "orgSlug": "grafanacom",
            "orgName": "grafanacom",
            "instanceId": null,
            "name": "SRE",
            "role": "Admin",
            "createdAt": "2023-01-04T06:43:51.000Z",
            "updatedAt": null,
            "firstUsed": "2023-01-04T06:44:26.000Z",
            "links": [
                {
                    "rel": "self",
                    "href": "/orgs/grafanacom/api-keys/SRE"
                },
                {
                    "rel": "org",
                    "href": "/orgs/grafanacom"
                }
            ]
        }
    ],
    "orderBy": "name",
    "direction": "asc",
    "links": [
        {
            "rel": "self",
            "href": "/orgs/grafanacom/api-keys"
        }
    ]
}

Create API key

POST https://grafana.com/api/orgs/<org_slug>/api-keys

Request Body

Name	Type	Description	Required
`name`	String	API key name	Yes
`role`	String	Permission level of API key. One of `Viewer`, `Editor`, `Admin`, or `MetricsPublisher`.	Yes

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
409	Conflict.

Example response:

{
    "id": 5046212,
    "orgId": 652945,
    "orgSlug": "grafanacom",
    "orgName": "grafanacom",
    "instanceId": null,
    "name": "createapikey",
    "role": "Admin",
    "createdAt": "2023-01-04T07:50:54.000Z",
    "updatedAt": null,
    "firstUsed": null,
    "token": "eyJrIjoiZmU5ZDlmY2JkODkzNTg4ZGUyYTJhNmJiZGJiMWYwNjQyMGM0MzBkNiIsIm4iOiJjcmVhdGVhcGlrZXkiLCJpZCI6NjUyOTkyf",
    "links": [
        {
            "rel": "self",
            "href": "/orgs/grafanacom/api-keys/createapikey"
        },
        {
            "rel": "org",
            "href": "/orgs/grafanacom"
        }
    ]
}

Delete API key

DELETE https://grafana.com/api/orgs/<org_slug>/api-keys/<api key name>

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
404	API Key not found.

Example response:

true

Stacks

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.

List stacks

GET https://grafana.com/api/orgs/<org_slug>/instances

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
403	Forbidden.

Example response:

{
    "items": [
        {
            "id": 007303,
            "orgId": 052992,
            "orgSlug": "grafanacom",
            "orgName": "grafanacom",
            "type": "grafana",
            "name": "cloudapistack.grafana.net",
            "url": "https://cloudapistack.grafana.net",
            "slug": "cloudapistack",
            "version": "stable",
            "description": "",
            "status": "active",
            "gateway": "istio",
            "createdAt": "2023-01-04T06:43:24.000Z",
            "createdBy": "foobar",
            "updatedAt": null,
            "updatedBy": "",
            "trial": 0,
            "trialExpiresAt": null,
            "clusterId": 69,
            "clusterSlug": "prod-us-central-0",
            "clusterName": "prod-us-central-0",
            "plan": "gcloud",
            "planName": "Grafana Cloud",
            "billingStartDate": "2023-01-04T06:43:23.000Z",
            "billingEndDate": null,
            "billingActiveUsers": 0,
            "billingGrafanaActiveUsers": 0,
            "billingOnCallActiveUsers": 0,
            "currentActiveUsers": 0,
            "currentActiveAdminUsers": 0,
            "currentActiveEditorUsers": 0,
            "currentActiveViewerUsers": 0,
            "dailyUserCnt": 0,
            "dailyAdminCnt": 0,
            "dailyEditorCnt": 0,
            "dailyViewerCnt": 0,
            "dashboardCnt": 8,
            "datasourceCnts": {},
            "userQuota": 10,
            "dashboardQuota": -1,
            "alertQuota": -1,
            "alertCnt": 0,
            "ssl": true,
            "customAuth": true,
            "customDomain": true,
            "support": true,
            "runningVersion": "9.3.2-45365 (commit: ef5286dd77, branch: v9.3.x)",
            "machineLearning": 0,
            "incident": 0,
            "hmInstancePromId": 715391,
            "hmInstancePromUrl": "https://prometheus-us-central1.grafana.net",
            "hmInstancePromName": "cloudapistack-prom",
            "hmInstancePromStatus": "active",
            "hmInstancePromCurrentUsage": 0,
            "hmInstancePromCurrentActiveSeries": 0,
            "hmInstanceGraphiteId": 715392,
            "hmInstanceGraphiteUrl": "https://graphite-prod-10-prod-us-central-0.grafana.net",
            "hmInstanceGraphiteName": "cloudapistack-graphite",
            "hmInstanceGraphiteType": "graphite-v5",
            "hmInstanceGraphiteStatus": "active",
            "hmInstanceGraphiteCurrentUsage": 0,
            "hlInstanceId": 356665,
            "hlInstanceUrl": "https://logs-prod-017.grafana.net",
            "hlInstanceName": "cloudapistack-logs",
            "hlInstanceStatus": "active",
            "hlInstanceCurrentUsage": 0,
            "amInstanceId": 355647,
            "amInstanceName": "cloudapistack-alerts",
            "amInstanceUrl": "https://alertmanager-us-central1.grafana.net",
            "amInstanceStatus": "active",
            "amInstanceGeneratorUrl": "https://cloudapistack.grafana.net",
            "amInstanceGeneratorUrlDatasource": "",
            "htInstanceId": 353178,
            "htInstanceUrl": "https://tempo-us-central1.grafana.net",
            "htInstanceName": "cloudapistack-traces",
            "htInstanceStatus": "active",
            "regionId": 1,
            "regionSlug": "us",
            "links": [
                {
                    "rel": "self",
                    "href": "/instances/cloudapistack"
                },
                {
                    "rel": "org",
                    "href": "/orgs/grafanacom"
                },
                {
                    "rel": "plugins",
                    "href": "/instances/cloudapistack/plugins"
                }
            ]
        }
    ],
    "orderBy": "name",
    "direction": "asc",
    "total": 1,
    "pages": 1,
    "pageSize": 1000000,
    "page": 1,
    "links": [
        {
            "rel": "self",
            "href": "/instances"
        }
    ]
}

Create stack

Note: This POST request accepts lowercase characters only.

POST https://grafana.com/api/instances

Request Body

Name	Type	Description	Required
`name`	String	Name of stack. Conventionally matches the URL of the instance. For example, `<stack_slug>.grafana.net`.	Yes
`slug`	String	Subdomain that the Grafana instance will be available at. For example, if you set the slug to `<stack_slug>`, the instance will be available at `https://<stack_slug>.grafana.net`.	Yes
`url`	String	If you use a custom domain for the instance, you must provide it here. For example, `“https://grafana.yourdoman.io”`.	No
`region`	String	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`.	No

Note: For the custom domain, you must set up a CNAME record that points to <stack_slug>.grafana.net before you can specify the domain.

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
403	Forbidden.
409	Conflict.

Example response:

{
    "id": 507363,
    "orgId": 652992,
    "orgSlug": "grafanacom",
    "orgName": "grafanacom",
    "type": "grafana",
    "name": "createcloudstack",
    "url": "https://createcloudstack.grafana.net",
    "slug": "createcloudstack",
    "version": "stable",
    "description": "",
    "status": "active",
    "gateway": "istio",
    "createdAt": "2023-01-04T08:20:07.000Z",
    "createdBy": "testengineer",
    "updatedAt": null,
    "updatedBy": "",
    "trial": 0,
    "trialExpiresAt": null,
    "clusterId": 69,
    "clusterSlug": "prod-us-central-0",
    "clusterName": "prod-us-central-0",
    "plan": "gcloud",
    "planName": "Grafana Cloud",
    "billingStartDate": "2023-01-04T08:20:06.000Z",
    "billingEndDate": null,
    "billingActiveUsers": 0,
    "billingGrafanaActiveUsers": 0,
    "billingOnCallActiveUsers": 0,
    "currentActiveUsers": 0,
    "currentActiveAdminUsers": 0,
    "currentActiveEditorUsers": 0,
    "currentActiveViewerUsers": 0,
    "dailyUserCnt": 0,
    "dailyAdminCnt": 0,
    "dailyEditorCnt": 0,
    "dailyViewerCnt": 0,
    "dashboardCnt": 0,
    "datasourceCnts": {},
    "userQuota": 10,
    "dashboardQuota": -1,
    "alertQuota": -1,
    "alertCnt": 0,
    "ssl": true,
    "customAuth": true,
    "customDomain": true,
    "support": true,
    "runningVersion": "",
    "machineLearning": 0,
    "incident": 0,
    "hmInstancePromId": 715511,
    "hmInstancePromUrl": "https://prometheus-us-central1.grafana.net",
    "hmInstancePromName": "createcloudstack-prom",
    "hmInstancePromStatus": "active",
    "hmInstancePromCurrentUsage": 0,
    "hmInstancePromCurrentActiveSeries": 0,
    "hmInstanceGraphiteId": 715512,
    "hmInstanceGraphiteUrl": "https://graphite-prod-10-prod-us-central-0.grafana.net",
    "hmInstanceGraphiteName": "createcloudstack-graphite",
    "hmInstanceGraphiteType": "graphite-v5",
    "hmInstanceGraphiteStatus": "active",
    "hmInstanceGraphiteCurrentUsage": 0,
    "hlInstanceId": 356725,
    "hlInstanceUrl": "https://logs-prod-017.grafana.net",
    "hlInstanceName": "createcloudstack-logs",
    "hlInstanceStatus": "active",
    "hlInstanceCurrentUsage": 0,
    "amInstanceId": 355707,
    "amInstanceName": "createcloudstack-alerts",
    "amInstanceUrl": "https://alertmanager-us-central1.grafana.net",
    "amInstanceStatus": "active",
    "amInstanceGeneratorUrl": "https://createcloudstack.grafana.net",
    "amInstanceGeneratorUrlDatasource": "",
    "htInstanceId": 353238,
    "htInstanceUrl": "https://tempo-us-central1.grafana.net",
    "htInstanceName": "createcloudstack-traces",
    "htInstanceStatus": "active",
    "regionId": 1,
    "regionSlug": "us",
    "links": [
        {
            "rel": "self",
            "href": "/instances/createcloudstack"
        },
        {
            "rel": "org",
            "href": "/orgs/grafanacom"
        },
        {
            "rel": "plugins",
            "href": "/instances/createcloudstack/plugins"
        }
    ]
}

Delete stack

DELETE https://grafana.com/api/instances/<stack_slug>

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
404	Cloud Stack not found.

Example response:

{
    "id": 507366,
    "orgId": 652992,
    "orgSlug": "grafanacom",
    "orgName": "grafanacom",
    "type": "grafana",
    "name": "createcloudstack",
    "url": "https://createcloudstack.grafana.net",
    "slug": "createcloudstack",
    "version": "stable",
    "description": "",
    "status": "deleted",
    "gateway": "istio",
    "createdAt": "2023-01-04T08:22:00.000Z",
    "createdBy": "ishanjain",
    "updatedAt": "2023-01-04T08:30:36.066Z",
    "updatedBy": "ishanjain",
    "trial": 0,
    "trialExpiresAt": null,
    "clusterId": 69,
    "clusterSlug": "prod-us-central-0",
    "clusterName": "prod-us-central-0",
    "plan": "gcloud",
    "planName": "Grafana Cloud",
    "billingStartDate": "2023-01-04T08:21:59.000Z",
    "billingEndDate": "2023-01-04T08:30:36.066Z",
    "billingActiveUsers": 0,
    "billingGrafanaActiveUsers": 0,
    "billingOnCallActiveUsers": 0,
    "currentActiveUsers": 0,
    "currentActiveAdminUsers": 0,
    "currentActiveEditorUsers": 0,
    "currentActiveViewerUsers": 0,
    "dailyUserCnt": 0,
    "dailyAdminCnt": 0,
    "dailyEditorCnt": 0,
    "dailyViewerCnt": 0,
    "dashboardCnt": 0,
    "datasourceCnts": {},
    "userQuota": 10,
    "dashboardQuota": -1,
    "alertQuota": -1,
    "alertCnt": 0,
    "ssl": true,
    "customAuth": true,
    "customDomain": true,
    "support": true,
    "runningVersion": "9.3.2-45365 (commit: ef5286dd77, branch: v9.3.x)",
    "machineLearning": 0,
    "incident": 0,
    "hmInstancePromId": 715517,
    "hmInstancePromUrl": "https://prometheus-us-central1.grafana.net",
    "hmInstancePromName": "createcloudstack-prom",
    "hmInstancePromStatus": "active",
    "hmInstancePromCurrentUsage": 0,
    "hmInstancePromCurrentActiveSeries": 0,
    "hmInstanceGraphiteId": 715518,
    "hmInstanceGraphiteUrl": "https://graphite-prod-10-prod-us-central-0.grafana.net",
    "hmInstanceGraphiteName": "createcloudstack-graphite",
    "hmInstanceGraphiteType": "graphite-v5",
    "hmInstanceGraphiteStatus": "active",
    "hmInstanceGraphiteCurrentUsage": 0,
    "hlInstanceId": 356728,
    "hlInstanceUrl": "https://logs-prod-017.grafana.net",
    "hlInstanceName": "createcloudstack-logs",
    "hlInstanceStatus": "active",
    "hlInstanceCurrentUsage": 0,
    "amInstanceId": 355710,
    "amInstanceName": "createcloudstack1-alerts",
    "amInstanceUrl": "https://alertmanager-us-central1.grafana.net",
    "amInstanceStatus": "active",
    "amInstanceGeneratorUrl": "https://createcloudstack.grafana.net",
    "amInstanceGeneratorUrlDatasource": "",
    "htInstanceId": 353241,
    "htInstanceUrl": "https://tempo-us-central1.grafana.net",
    "htInstanceName": "createcloudstack-traces",
    "htInstanceStatus": "active",
    "regionId": 1,
    "regionSlug": "us",
    "links": [
        {
            "rel": "self",
            "href": "/instances/507366"
        },
        {
            "rel": "org",
            "href": "/orgs/grafanacom"
        },
        {
            "rel": "plugins",
            "href": "/instances/507366/plugins"
        }
    ]
}

Restart Grafana

POST https://grafana.com/api/instances/<stack_slug>/restart

Responses

The following responses may be returned.

Code	Description
200	Successful operation
401	API token is missing or invalid.
404	Cloud Stack not found

Example response:

true

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.

Request Body

Name	Type	Description	Required
`name`	String	Name of the API key.	Yes
`role`	String	Access level/Grafana role for the key. Can be one of the following values: `Viewer`, `Editor`, or `Admin`.	Yes
`secondsToLive`	Number	Key expiration in seconds. If it is a positive number, an expiration date for the key is set. The key will never expire if it is null, zero, or is omitted completely (unless `api_key_max_seconds_to_live` configuration option is set).	No

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
404	Cloud Stack not found.
409	Conflict.

Example response:

{
    "id": 1,
    "name": "testkey",
    "key": "eyJrIjoiMWpSRVhRUVJHZlc3NW1laklzV3htQUt0cUxtS3RuWFUiLCJuIjoidGVzdGtleSIsImlkIjoxf"
}

List data sources

GET https://grafana.com/api/instances/<stack_slug>/datasources

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
404	Cloud Stack not found.
409	Unexpected Parameter (InvalidArgument).

Example response:

{
    "items": [
        {
            "id": 25744816,
            "instanceId": 2860016,
            "name": "grafanacloud-usage",
            "type": "prometheus",
            "access": "proxy",
            "grafanaOrgId": 1,
            "url": "https://billing.grafana.net/api/prom",
            "password": "",
            "user": "",
            "database": "",
            "basicAuth": 1,
            "basicAuthUser": "65299211",
            "withCredentials": 0,
            "isDefault": 0,
            "jsonData": {
                "timeInterval": "60s",
                "timeout": "150",
                "prometheusVersion": "2.3.0",
                "prometheusType": "Mimir"
            },
            "version": 1,
            "editable": 1,
            "delete": 0,
            "createdAt": "2023-01-04T08:20:13.484927Z",
            "updatedAt": null
        },
        {
            "id": 25744915,
            "instanceId": 2860016,
            "name": "grafanacloud-createcloudstack-logs",
            "type": "loki",
            "access": "proxy",
            "grafanaOrgId": 1,
            "url": "https://logs-prod-017.grafana.net",
            "password": "",
            "user": "",
            "database": "",
            "basicAuth": 1,
            "basicAuthUser": "3567215",
            "withCredentials": 0,
            "isDefault": 0,
            "jsonData": {
                "timeout": "300"
            },
            "version": 1,
            "editable": 1,
            "delete": 0,
            "createdAt": "2023-01-04T08:20:13.625323Z",
            "updatedAt": null
        }
    ]
}

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

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
404	Cloud Stack not found.
409	Unexpected Parameter (InvalidArgument).

Example response:

{
    "items": [
        {
            "id": 256529,
            "instanceId": 507363,
            "instanceUrl": "https://createcloudstack.grafana.net",
            "pluginId": 663,
            "pluginSlug": "grafana-github-datasource",
            "pluginName": "GitHub",
            "version": "1.3.1",
            "latestVersion": "1.3.1",
            "createdAt": "2023-01-04T09:33:55.000Z",
            "updatedAt": null,
            "links": [
                {
                    "rel": "self",
                    "href": "/instances/507363/plugins/grafana-github-datasource"
                },
                {
                    "rel": "instance",
                    "href": "/instances/507363"
                }
            ]
        }
    ],
    "orderBy": "pluginName",
    "direction": "asc",
    "links": [
        {
            "rel": "self",
            "href": "/instances/createcloudstack/plugins"
        }
    ]
}

Add a plugin to instance

POST https://grafana.com/api/instances/<stack_slug>/plugins

Request Body

Name	Type	Description	Required
`plugin`	String	Name of the plugin, e.g., `grafana-github-datasource`.	Yes
`version`	String	Version of the plugin to install. Defaults to `latest`.	No

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
404	Plugin or Cloud Stack not found.
409	Unexpected Parameter (InvalidArgument).

Example response:

{
    "id": 256519,
    "instanceId": 507363,
    "instanceUrl": "https://createcloudstack.grafana.net",
    "instanceSlug": "createcloudstack",
    "pluginId": 663,
    "pluginSlug": "grafana-github-datasource",
    "pluginName": "GitHub",
    "version": "1.3.1",
    "latestVersion": "1.3.1",
    "createdAt": "2023-01-04T08:50:42.000Z",
    "updatedAt": null,
    "links": [
        {
            "rel": "self",
            "href": "/instances/createcloudstack/plugins/grafana-github-datasource"
        },
        {
            "rel": "instance",
            "href": "/instances/createcloudstack"
        }
    ]
}

Get installed plugin info

GET https://grafana.com/api/instances/<stack_slug>/plugins/<plugin>

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
404	Plugin or Cloud Stack not found.
409	Unexpected Parameter (InvalidArgument).

Example response:

{
    "id": 256519,
    "instanceId": 507363,
    "instanceUrl": "https://createcloudstack.grafana.net",
    "instanceSlug": "createcloudstack",
    "pluginId": 663,
    "pluginSlug": "grafana-github-datasource",
    "pluginName": "GitHub",
    "version": "1.3.1",
    "latestVersion": "1.3.1",
    "createdAt": "2023-01-04T08:50:42.000Z",
    "updatedAt": null,
    "links": [
        {
            "rel": "self",
            "href": "/instances/createcloudstack/plugins/grafana-github-datasource"
        },
        {
            "rel": "instance",
            "href": "/instances/createcloudstack"
        }
    ]
}

Update installed plugin version

POST https://grafana.com/api/instances/<stack_slug>/plugins/<plugin>

Request Body

Name	Type	Description	Required
`version`	String	Updated version of the plugin.	Yes

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
404	Plugin or Cloud Stack not found.
409	Unexpected Parameter (InvalidArgument).

Example response:

{
    "id": 256519,
    "instanceId": 507363,
    "instanceUrl": "https://createcloudstack.grafana.net",
    "instanceSlug": "createcloudstack",
    "pluginId": 663,
    "pluginSlug": "grafana-github-datasource",
    "pluginName": "GitHub",
    "version": "1.3.0",
    "latestVersion": "1.3.1",
    "createdAt": "2023-01-04T08:50:42.000Z",
    "updatedAt": "2023-01-04T08:55:00.088Z",
    "links": [
        {
            "rel": "self",
            "href": "/instances/createcloudstack/plugins/grafana-github-datasource"
        },
        {
            "rel": "instance",
            "href": "/instances/createcloudstack"
        }
    ]
}

Delete an installed plugin

DELETE https://grafana.com/api/instances/<stack_slug>/plugins/<plugin>

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
404	Plugin or Cloud Stack not found.
409	Unexpected Parameter (InvalidArgument).

Example response:

{
    "id": 256519,
    "instanceId": 507363,
    "instanceUrl": "https://createcloudstack.grafana.net",
    "instanceSlug": "createcloudstack",
    "pluginId": 663,
    "pluginSlug": "grafana-github-datasource",
    "pluginName": "GitHub",
    "version": "1.3.1",
    "latestVersion": "1.3.1",
    "createdAt": "2023-01-04T08:50:42.000Z",
    "updatedAt": "2023-01-04T08:59:20.794Z",
    "links": [
        {
            "rel": "self",
            "href": "/instances/createcloudstack/plugins/grafana-github-datasource"
        },
        {
            "rel": "instance",
            "href": "/instances/createcloudstack"
        }
    ]
}

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

Responses

The following responses may be returned.

Code	Description
200	Successful operation.
401	API token is missing or invalid.
409	Unexpected Parameter (InvalidArgument).

Example response:

{
    "items": [
        {
            "id": 1,
            "status": "active",
            "slug": "us",
            "name": "GCP US Central",
            "description": "United States",
            "provider": "gcp",
            "createdAt": "2021-08-20T20:00:27.000Z",
            "updatedAt": "2022-12-12T12:29:37.000Z"
        },
        {
            "id": 2,
            "status": "active",
            "slug": "us-azure",
            "name": "Azure US Central",
            "description": "United States (Azure)",
            "provider": "azure",
            "createdAt": "2021-08-20T20:08:03.000Z",
            "updatedAt": "2022-11-29T12:04:00.000Z"
        },
        {
            "id": 3,
            "status": "active",
            "slug": "eu",
            "name": "GCP Belgium",
            "description": "Europe",
            "provider": "gcp",
            "createdAt": "2021-08-20T20:28:52.000Z",
            "updatedAt": "2022-12-05T18:05:33.000Z"
        },
        {
            "id": 4,
            "status": "active",
            "slug": "au",
            "name": "GCP Australia",
            "description": "Australia",
            "provider": "gcp",
            "createdAt": "2021-11-16T22:03:18.000Z",
            "updatedAt": "2022-09-22T09:27:47.000Z"
        }
    ],
    "orderBy": "id",
    "direction": "asc",
    "total": 9,
    "pages": 1,
    "pageSize": 1000000,
    "page": 1,
    "links": [
        {
            "rel": "self",
            "href": "/stack-regions"
        }
    ]
}

Access policies and tokens

Note: The Access Policies and Tokens API endpoints are early access features. This feature is under active development.

This API specification describes endpoints used to manage the new-generation resources for authentication and authorization.

Access policies and tokens use access policy, token, scope, realm, and labelselector resources. For more information about these resources, refer to the Grafana Cloud Acccess Policies documentation.

All API requests must specify a token in the request’s Authorization header.

You may use a legacy API key obtained from https://grafana.com/orgs/{org}/api-keys or a token created via this API.

This API relies on stack and org IDs. Your stack IDs can be obtained from https://grafana.com/api/orgs/{org}/instances and your org ID can be obtained from https://grafana.com/api/orgs/{org}.

Paginated endpoints optionally accept both pageSize and pageCursor query parameters. If pageCursor is not provided or empty, the first page will be requested. The next page’s URL can be obtained from the current page’s metadata.pagination.nextPage property. If that field is null, you’ve reached the last page and there are no records left.

Create an access policy

Create an access policy with the POST method.

POST http://www.grafana.com/api/v1/accesspolicies

Parameters

Name	Type	Description	Required
`region`	String	Region where the API is deployed. Generally where the stack is deployed.	Yes

Request body

Example request:

{
  "name": "stack-readers",
  "displayName": "Stack Readers",
  "scopes": [
    "metrics:read",
    "logs:read",
    "traces:read",
    "alerts:read"
  ],
  "realms": [
    {
      "type": "stack",
      "identifier": "123",
      "labelPolicies": [
        {
          "selector": "{env != \"dev\"}"
        }
      ]
    }
  ]
}

Responses

The following responses may be returned.

Code	Description
200	Successful operation

Example response:

{
  "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "orgId": "1",
  "name": "stack-readers",
  "displayName": "Stack Readers",
  "scopes": [
    "metrics:read",
    "logs:read",
    "traces:read",
    "alerts:read"
  ],
  "realms": [
    {
      "type": "stack",
      "identifier": "123",
      "labelPolicies": [
        {
          "selector": "{env != \"dev\"}"
        }
      ]
    }
  ],
  "createdAt": "2022-06-08T20:07:21.223Z",
  "updatedAt": "2022-06-08T20:07:21.223Z"
}

Code	Description
400	Bad request
401	API token is missing or invalid.
409	Conflict

List access policies

List specified access policies with the GET method.

GET http://www.grafana.com/api/v1/accesspolicies

Parameters

Name	Type	Description	Required
`name`	Query	Name of the access policy to filter by.	No
`realmType`	String	Query. Available values are `org` and `stack`.	No
`realmIdentifier`	String	Requires realmType. Identifier of the realm.	No
`pageSize`	String	The number of records to be returned per page. The default value is 500; the maximum value is 500.	No
`pageCursor`	String	Query. A cursor used for paging through the results. The first page will be fetched when not provided.	No
`region`	String	Query. Region where the API is deployed. Generally where the stack is deployed. Available values are `us`, `eu`, and `au`.	Yes

Responses

The following responses may be returned.

Code	Description
200	Successful operation

Example response:

{
  "items": [
    {
      "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
      "orgId": "1",
      "name": "stack-readers",
      "displayName": "Stack Readers",
      "scopes": [
        "metrics:read",
        "logs:read",
        "traces:read",
        "alerts:read"
      ],
      "realms": [
        {
          "type": "stack",
          "identifier": "123",
          "labelPolicies": [
            {
              "selector": "{env != \"dev\"}"
            }
          ]
        }
      ],
      "createdAt": "2022-06-08T16:47:46.151Z",
      "updatedAt": "2022-06-08T16:47:46.151Z"
    }
  ],
  "metadata": {
    "pagination": {
      "pageSize": 500,
      "pageCursor": "ZDMyYzZhODktZjU1ZC00NGViLWJmYWEtMTEyYmE2NTFlNDJifDIwMjItMDQtMTFUMTI6NTQ6MDBa",
      "nextPage": "/v1/accesspolicies?pageCursor=ZDMyYzZhODktZjU1ZC00NGViLWJmYWEtMTEyYmE2NTFlNDJifDIwMjItMDQtMTFUMTI6NTQ6MDBa"
    }
  }
}

Code	Description
400	Bad request
401	API token is missing or invalid.

List one access policy

List one access policy with the GET method.

GET http://www.grafana.com/api/v1/accesspolicies/{accessPolicyID}

Parameters

Name	Type	Description	Required
`region`	String	Query. Region where the API is deployed. Generally where the stack is deployed. Available values are `us`, `eu`, and `au`.	Yes
`accessPolicyId`	String	($uuid). Path. ID of the access policy.	Yes

Responses

The following responses may be returned.

Code	Description
200	Successful operation

Example response:

{
  "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "orgId": "1",
  "name": "stack-readers",
  "displayName": "Stack Readers",
  "scopes": [
    "metrics:read",
    "logs:read",
    "traces:read",
    "alerts:read"
  ],
  "realms": [
    {
      "type": "stack",
      "identifier": "123",
      "labelPolicies": [
        {
          "selector": "{env != \"dev\"}"
        }
      ]
    }
  ],
  "createdAt": "2022-06-08T21:06:27.853Z",
  "updatedAt": "2022-06-08T21:06:27.853Z"
}

Code	Description
400	Bad request
401	API token is missing or invalid.

Update an access policy

Update an existing access policy with the POST method.

POST http://www.grafana.com/api/v1/accesspolicies/{accessPolicyId}

Parameters

Name	Type	Description	Required
`region`	String	Query. Region where the API is deployed. Generally where the stack is deployed. Available values are `us`, `eu`, and `au`.	Yes
`accessPolicyId`	String	(`UUID`). Path. ID of the access policy.	Yes

Request body

The request body specifies the revised access policy.

Example request:

{
  "displayName": "Stack Readers",
  "scopes": [
    "metrics:read",
    "logs:read",
    "traces:read",
    "alerts:read"
  ],
  "realms": [
    {
      "type": "stack",
      "identifier": "123",
      "labelPolicies": [
        {
          "selector": "{env != \"dev\"}"
        }
      ]
    }
  ]
}

Responses

The following responses may be returned.

Code	Description
200	Successful operation

Example response:

{
  "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "orgId": "1",
  "name": "stack-readers",
  "displayName": "Stack Readers",
  "scopes": [
    "metrics:read",
    "logs:read",
    "traces:read",
    "alerts:read"
  ],
  "realms": [
    {
      "type": "stack",
      "identifier": "123",
      "labelPolicies": [
        {
          "selector": "{env != \"dev\"}"
        }
      ]
    }
  ],
  "createdAt": "2022-06-08T21:10:37.011Z",
  "updatedAt": "2022-06-08T21:10:37.011Z"
}

Code	Description
400	Bad request
401	API token is missing or invalid.

Delete an access policy

Remove an access policy with the DELETE method.

DELETE http://www.grafana.com/api/v1/accesspolicies/{accessPolicyId}

Parameters

Name	Type	Description	Required
`region`	String	Query. Region where the API is deployed. Generally where the stack is deployed. Available values are `us`, `eu`, and `au`.	Yes
`accessPolicyId`	String	(`UUID`). Path. ID of the access policy.	Yes

Responses

The following responses may be returned.

Code	Description
204	Access policy deleted successfully.
400	Bad request
401	API token is missing or invalid

Create a token

Create a token with the POST method.

POST http://www.grafana.com/api/v1/tokens

Parameters

Name	Type	Description	Required
`region`	String	Query. Region where the API is deployed. Generally where the stack is deployed. Available values are `us`, `eu`, and `au`.	Yes

Request body

The request body contains details about the token being created.

Example request:

{
  "accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "name": "mytoken",
  "displayName": "My Token",
  "expiresAt": "2022-06-08T22:05:46.958Z"
}

Responses

The following responses may be returned.

Code	Description
200	Successful operation

Example response:

{
  "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "name": "mytoken",
  "displayName": "My Token",
  "expiresAt": "2022-06-08T22:05:46.959Z",
  "firstUsedAt": "2022-06-08T22:05:46.959Z",
  "createdAt": "2022-06-08T22:05:46.959Z",
  "updatedAt": "2022-06-08T22:05:46.959Z",
  "token": "glc_eyJrIjoiZjI0YzZkNGEwZDBmZmZjMmUzNTU2ODcxMmY0ZWZlNTQ1NTljMDFjOCIsIm4iOiJteXRva2VuIiwiaWQiOjF9"
}

Code	Description
400	Bad request
401	API token is missing or invalid
409	Conflict

List a set of tokens

List a set of tokens with the GET method.

GET http://www.grafana.com/api/v1/tokens

Parameters

Name	Type	Description	Required
`accessPolicyId`	String	Query. ID of the access policy to filter by.	No
`accessPolicyName`	String	Query. Name of the access policy to filter by.	No
`accessPolicyRealmType`	String	Query. Type of the access policy realm. Available values are `org` and `stack`.	No
`accessPolicyRealmIdentifier`	String	Query. Identifier of the access policy realm. Requires accessPolicyRealmType.	No
`name`	String	Query. Name of the Token to filter by.	No
`expiresBefore`	String	Query. Time (in ISO8601 UTC format) to filter tokens that have expiresAt set before the given time.	No
`expiresAfter`	String	Query. Time (in ISO8601 UTC format) to filter tokens that have expiresAt set after te given time.	No
`pageSize`	String	Query. The number of records to be returned per page. Default value is `500`; the maximum value is `500`.	No
`pageCursor`	String	Query. A cursor used for paging through the results. The first page will be fetched when not provided.	No
`region`	String	Query. Region where the API is deployed. Generally where the stack is deployed. Available values are `us`, `eu`, and `au`.	Yes

Responses

The following responses may be returned.

Code	Description
200	Successful operation

Example response:

{
  "items": [
    {
      "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
      "accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
      "name": "mytoken",
      "displayName": "My Token",
      "expiresAt": "2022-06-08T22:11:05.614Z",
      "firstUsedAt": "2022-06-08T22:11:05.614Z",
      "createdAt": "2022-06-08T22:11:05.614Z",
      "updatedAt": "2022-06-08T22:11:05.614Z"
    }
  ],
  "metadata": {
    "pagination": {
      "pageSize": 500,
      "pageCursor": "ZDMyYzZhODktZjU1ZC00NGViLWJmYWEtMTEyYmE2NTFlNDJifDIwMjItMDQtMTFUMTI6NTQ6MDBa",
      "nextPage": "/v1/accesspolicies?pageCursor=ZDMyYzZhODktZjU1ZC00NGViLWJmYWEtMTEyYmE2NTFlNDJifDIwMjItMDQtMTFUMTI6NTQ6MDBa"
    }
  }
}

Code	Description
400	Bad request
401	API token is missing or invalid

List a single token

List a specified token with the GET method.

GET http://www.grafana.com/api/v1/tokens/{tokenId}

Parameters

Name	Type	Description	Required
`region`	String	Query. Region where the API is deployed. Generally where the stack is deployed. Available values are `us`, `eu`, and `au`.	Yes
`tokenId`	String	(`UUID`). Path. ID of the Token.	Yes

Responses

The following responses may be returned.

Code	Description
200	Successful operation

Example response:

{
  "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "name": "mytoken",
  "displayName": "My Token",
  "expiresAt": "2022-06-09T04:31:23.559Z",
  "firstUsedAt": "2022-06-09T04:31:23.559Z",
  "createdAt": "2022-06-09T04:31:23.559Z",
  "updatedAt": "2022-06-09T04:31:23.559Z"
}

Code	Description
400	Bad request
401	API token is missing or invalid

Update a token

Update a specified token with the POST method.

POST http://www.grafana.com/api/v1/tokens/{tokenId}

Parameters

Name	Type	Description	Required
`region`	String	Query. Region where the API is deployed. Generally where the stack is deployed. Available values are `us`, `eu`, and `au`.	Yes
`tokenId`	String	(`UUID`). Path. ID of the Token.	Yes

Request body

The request body contains the updated values being applied to the token.

Example request:

{
  "displayName": "My token"
}

Responses

The following responses may be returned.

Code	Description
200	Successful operation

Example response:

{
  "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "name": "mytoken",
  "displayName": "My token",
  "expiresAt": "2022-06-09T04:43:16.296Z",
  "firstUsedAt": "2022-06-09T04:43:16.296Z",
  "createdAt": "2022-06-09T04:43:16.296Z",
  "updatedAt": "2022-06-09T04:43:16.296Z"
}

Code	Description
400	Bad request
401	API token is missing or invalid

Delete a token

Remove a specified token with the DELETE method.

DELETE http://www.grafana.com/api/v1/tokens/{tokenId}

Parameters

Name	Type	Description	Required
`region`	String	Query. Region where the API is deployed. Generally where the stack is deployed. Available values are `us`, `eu`, and `au`.	Yes
`tokenId`	String	(`UUID`). Path. ID of the Token.	Yes

Responses

The following responses may be returned.

Code	Description
204	Token deleted successfully
400	Bad request
401	API token is missing or invalid

Authentication

API keys

List API keys

Responses

Create API key

Request Body

Responses

Delete API key

Responses

Stacks

List stacks

Responses

Create stack

Request Body

Responses

Delete stack

Responses

Restart Grafana

Responses

Create Hosted Grafana instance API keys

Request Body

Responses

List data sources

Responses

Grafana plugins

List plugins installed on an instance

Responses

Add a plugin to instance

Request Body

Responses

Get installed plugin info

Responses

Update installed plugin version

Request Body

Responses

Delete an installed plugin

Responses

Regions

List regions

Responses

Access policies and tokens

Create an access policy

Parameters

Request body

Responses

List access policies

Parameters

Responses

List one access policy

Parameters

Responses

Update an access policy

Parameters

Request body

Responses

Delete an access policy

Parameters

Responses

Create a token

Parameters

Request body

Responses

List a set of tokens

Parameters

Responses

List a single token

Parameters

Responses

Update a token

Parameters

Request body

Responses

Delete a token

Parameters

Responses

Related documentation

Related resources from Grafana Labs