Menu
Grafana Cloud

Grafana Cloud API

The Grafana Cloud API, sometimes referred to as the Grafana.com API or GCOM API, allows you to interact with resources from your Grafana Cloud Stack programmatically.

Below is the list of approved, static endpoints and calls for general use. Any other paths are subject to change and are not maintained for general user consumption.

Note

If you need to manage or access resources from your Grafana instance—such as dashboards, alerts, data sources, users, and more—refer to the HTTP API instead.

Authentication

You must create a Cloud Access Policy and token to use the Cloud API. To create a Grafana Cloud Access Policy, refer to Create an access policy.

Requests to the API are authenticated using the Authorization header:

http
Authorization: Bearer <CLOUD ACCESS POLICY TOKEN>

Access policies and tokens

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

Note

Access policies and tokens must have a unique combination of name, org ID, and region.

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

This API relies on stack and org IDs. You can get your stack ID from the https://grafana.com/api/orgs/{org}/instances endpoint. You can get your org ID from the https://grafana.com/api/orgs/{org} endpoint.

Paginated endpoints optionally accept both pageSize and pageCursor query parameters. If you omit the pageCursor parameter, or provide an empty pageCursor value, you receive the first page.

You can get the next page’s URL 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.

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

Parameters

NameTypeDescriptionRequired
regionStringRegion for the Access Policy. Generally where the stack is deployed.Yes

Request body

Example request:

json
{
  "name": "stack-readers",
  "displayName": "Stack Readers",
  "scopes": ["metrics:read", "logs:read", "traces:read", "alerts:read"],
  "realms": [
    {
      "type": "stack",
      "identifier": "123",
      "labelPolicies": [
        {
          "selector": "{env != \"dev\"}"
        }
      ]
    }
  ],
  "conditions": {
    "allowedSubnets": ["192.168.0.0/24", "10.1.2.99/32"]
  }
}

Responses

The following responses may be returned.

CodeDescription
200Successful operation

Example response:

json
{
  "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\"}"
        }
      ]
    }
  ],
  "conditions": {
    "allowedSubnets": ["192.168.0.0/24", "10.1.2.99/32"]
  },
  "createdAt": "2022-06-08T20:07:21.223Z",
  "updatedAt": "2022-06-08T20:07:21.223Z"
}
CodeDescription
400Bad request
401API token is missing or invalid.
409Conflict

List access policies

List specified access policies with the GET method.

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

Parameters

NameTypeDescriptionRequired
nameQueryName of the access policy to filter by.No
realmTypeStringQuery. Available values are org and stack.No
realmIdentifierStringRequires realmType. Identifier of the realm.No
pageSizeStringThe number of records to be returned per page. The default value is 500; the maximum value is 500.No
pageCursorStringQuery. A cursor used for paging through the results. If you omit the pageCursor parameter, or provide an empty pageCursor value, you receive the first page.No
regionStringQuery. Region of the Access Policy, as defined in the Access Policy. Some example values are us, eu, au, and prod-eu-west-3. For more information, refer to List regions.Yes
statusStringQuery. A status that can be used to filter the final list of Access Policies. Available values are active and inactive.No

Responses

The following responses may be returned.

CodeDescription
200Successful operation

Example response:

json
{
  "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\"}"
            }
          ]
        }
      ],
      "conditions": {
        "allowedSubnets": ["192.168.0.0/24", "10.1.2.99/32"]
      },
      "createdAt": "2022-06-08T16:47:46.151Z",
      "updatedAt": "2022-06-08T16:47:46.151Z",
      "status": "active"
    }
  ],
  "metadata": {
    "pagination": {
      "pageSize": 500,
      "pageCursor": "ZDMyYzZhODktZjU1ZC00NGViLWJmYWEtMTEyYmE2NTFlNDJifDIwMjItMDQtMTFUMTI6NTQ6MDBa",
      "nextPage": "/v1/accesspolicies?pageCursor=ZDMyYzZhODktZjU1ZC00NGViLWJmYWEtMTEyYmE2NTFlNDJifDIwMjItMDQtMTFUMTI6NTQ6MDBa"
    }
  }
}
CodeDescription
400Bad request
401API token is missing or invalid.

List one access policy

List one access policy with the GET method.

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

Parameters

NameTypeDescriptionRequired
regionStringQuery. Region of the Access Policy, as defined in the Access Policy. Some example values are us, eu, au, and prod-eu-west-3. For more information, refer to List regions.Yes
accessPolicyIdStringUUID. Path. ID of the access policy.Yes

Responses

The following responses may be returned.

CodeDescription
200Successful operation

Example response:

json
{
  "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\"}"
        }
      ]
    }
  ],
  "conditions": {
    "allowedSubnets": ["192.168.0.0/24", "10.1.2.99/32"]
  },
  "createdAt": "2022-06-08T21:06:27.853Z",
  "updatedAt": "2022-06-08T21:06:27.853Z",
  "status": "active"
}
CodeDescription
400Bad request
401API token is missing or invalid.

Update an access policy

Update an existing access policy with the POST method.

Note

To remove IP ranges do one of the following:

  • set allowedSubnets to an empty array ([])
  • set conditions to null or to an empty object ({}).
http
POST https://www.grafana.com/api/v1/accesspolicies/{accessPolicyId}

Parameters

NameTypeDescriptionRequired
regionStringQuery. Region of the Access Policy, as defined in the Access Policy. Some example values are us, eu, au, and prod-eu-west-3. For more information, refer to List regions.Yes
accessPolicyIdString(UUID). Path. ID of the access policy.Yes

Request body

The request body specifies the revised access policy.

Example request:

json
{
  "displayName": "Stack Readers",
  "scopes": ["metrics:read", "logs:read", "traces:read", "alerts:read"],
  "realms": [
    {
      "type": "stack",
      "identifier": "123",
      "labelPolicies": [
        {
          "selector": "{env != \"dev\"}"
        }
      ]
    }
  ],
  "conditions": {
    "allowedSubnets": ["192.168.99.100/32"]
  },
  "status": "active"
}

Responses

The following responses may be returned.

CodeDescription
200Successful operation

Example response:

json
{
  "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\"}"
        }
      ]
    }
  ],
  "conditions": {
    "allowedSubnets": ["192.168.99.100/32"]
  },
  "createdAt": "2022-06-08T21:10:37.011Z",
  "updatedAt": "2022-06-08T21:10:37.011Z",
  "status": "active"
}
CodeDescription
400Bad request
401API token is missing or invalid.

Delete an access policy

Remove an access policy with the DELETE method.

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

Parameters

NameTypeDescriptionRequired
regionStringQuery. Region of the Access Policy, as defined in the Access Policy. Some example values are us, eu, au, and prod-eu-west-3. For more information, refer to List regions.Yes
accessPolicyIdString(UUID). Path. ID of the access policy.Yes

Responses

The following responses may be returned.

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

Create a token

Create a token with the POST method.

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

Parameters

NameTypeDescriptionRequired
regionStringQuery. Region of the Access Policy, as defined in the Access Policy. Some example values are us, eu, au, and prod-eu-west-3. For more information, refer to List regions.Yes

Request body

The request body contains details about the token being created.

Example request:

json
{
  "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.

CodeDescription
200Successful operation

Example response:

json
{
  "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",
  "lastUsedAt": "2022-06-08T22:05:46.959Z",
  "createdAt": "2022-06-08T22:05:46.959Z",
  "updatedAt": "2022-06-08T22:05:46.959Z",
  "token": "glc_eyJrIjoiZjI0YzZkNGEwZDBmZmZjMmUzNTU2ODcxMmY0ZWZlNTQ1NTljMDFjOCIsIm4iOiJteXRva2VuIiwiaWQiOjF9"
}
CodeDescription
400Bad request
401API token is missing or invalid
409Conflict

List a set of tokens

List a set of tokens with the GET method.

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

Parameters

NameTypeDescriptionRequired
accessPolicyIdStringQuery. ID of the access policy to filter by.No
accessPolicyNameStringQuery. Name of the access policy to filter by.No
accessPolicyRealmTypeStringQuery. Type of the access policy realm. Available values are org and stack.No
accessPolicyRealmIdentifierStringQuery. Identifier of the access policy realm. Requires accessPolicyRealmType.No
nameStringQuery. Name of the Token to filter by.No
expiresBeforeStringQuery. Time (in ISO8601 UTC format) to filter tokens that have expiresAt set before the given time.No
expiresAfterStringQuery. Time (in ISO8601 UTC format) to filter tokens that have expiresAt set after the given time.No
pageSizeStringQuery. The number of records to be returned per page. Default value is 500; the maximum value is 500.No
pageCursorStringQuery. A cursor used for paging through the results. If you omit the pageCursor parameter, or provide an empty pageCursor value, you receive the first page.No
regionStringQuery. Region of the Access Policy, as defined in the Access Policy. Some example values are us, eu, au, and prod-eu-west-3. For more information, refer to List regions.Yes
accessPolicyStatusStringQuery. A filter to only list tokens which Access Policies are in the given status. Available values are active and inactive.No

Responses

The following responses may be returned.

CodeDescription
200Successful operation

Example response:

json
{
  "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",
      "lastUsedAt": "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"
    }
  }
}
CodeDescription
400Bad request
401API token is missing or invalid

List a single token

List a specified token with the GET method.

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

Parameters

NameTypeDescriptionRequired
regionStringQuery. Region of the Access Policy, as defined in the Access Policy. Some example values are us, eu, au, and prod-eu-west-3. For more information, refer to List regions.Yes
tokenIdString(UUID). Path. ID of the Token.Yes

Responses

The following responses may be returned.

CodeDescription
200Successful operation

Example response:

json
{
  "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",
  "lastUsedAt": "2022-06-09T04:31:23.559Z",
  "createdAt": "2022-06-09T04:31:23.559Z",
  "updatedAt": "2022-06-09T04:31:23.559Z"
}
CodeDescription
400Bad request
401API token is missing or invalid

Update a token

Update a specified token with the POST method.

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

Parameters

NameTypeDescriptionRequired
regionStringQuery. Region of the Access Policy, as defined in the Access Policy. Some example values are us, eu, au, and prod-eu-west-3. For more information, refer to List regions.Yes
tokenIdString(UUID). Path. ID of the Token.Yes

Request body

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

Example request:

json
{
  "displayName": "My token"
}

Responses

The following responses may be returned.

CodeDescription
200Successful operation

Example response:

json
{
  "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",
  "lastUsedAt": "2022-06-09T04:43:16.296Z",
  "createdAt": "2022-06-09T04:43:16.296Z",
  "updatedAt": "2022-06-09T04:43:16.296Z"
}
CodeDescription
400Bad request
401API token is missing or invalid

Delete a token

Remove a specified token with the DELETE method.

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

Parameters

NameTypeDescriptionRequired
regionStringQuery. Region of the Access Policy, as defined in the Access Policy. Some example values are us, eu, au, and prod-eu-west-3. For more information, refer to List regions.Yes
tokenIdString(UUID). Path. ID of the Token.Yes

Responses

The following responses may be returned.

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

Stacks

Note

Grafana Cloud Free includes 1 stack and Grafana Cloud Pro includes up to 3 stacks. Reach out to support about Grafana Cloud Advanced if you would like to add additional stacks to your account.

List stacks

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

Responses

The following responses may be returned.

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

Example response:

json
{
  "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.
http
POST https://grafana.com/api/instances

Request Body

NameTypeDescriptionRequired
nameStringName of stack. Conventionally matches the URL of the instance. For example, <STACK_SLUG>.grafana.net.Yes
slugStringSubdomain that the Grafana instance to make the instance available at. For example, if you set the slug to <STACK_SLUG>, the full URL for the instance is https://<STACK_SLUG>.grafana.net.Yes
urlStringIf you use a custom domain for the instance, you must provide it here. For example, "https://grafana.yourdoman.io".No
regionStringChoose 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, refer to List regions. If you don’t specify a region, the default is us.No
descriptionStringA short text that describes the purpose of the stack.No
labelsmap[String]StringAdd labels to a stack if you want to add a visual way to distinguish them in the UI. Labels are key:value pairs where the both the key and value can alphanumeric, ., - or /. Up to 10 labels are allowed. Example: {"team":"platform", "environment":"dev"}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.

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

Example response:

json
{
  "id": 507363,
  "orgId": 652992,
  "orgSlug": "grafanacom",
  "orgName": "grafanacom",
  "type": "grafana",
  "name": "createcloudstack",
  "url": "https://createcloudstack.grafana.net",
  "slug": "createcloudstack",
  "version": "stable",
  "labels": {
    "key": "value"
  },
  "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"
    }
  ]
}

Update stack

Note

This POST request accepts lowercase characters only.
http
POST https://grafana.com/api/instances/:idOrSlug

Request Body

NameTypeDescriptionRequired
descriptionStringA short text that describes the purpose of the stack.No
labelsmap[String]StringUpdates labels for a stack. Labels are key:value pairs where the both the key and value can alphanumeric, ., - or /. Up to 10 labels are allowed. To remove a label, just omit it in this request. To remove all labels send an empty object. Example: {"team":"platform", "environment":"dev"}No
nameStringName of stack. Conventionally matches the URL of the instance. For example, <STACK_SLUG>.grafana.net.No

Responses

The following responses may be returned.

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

Example response:

json
{
  "id": 507363,
  "orgId": 652992,
  "orgSlug": "grafanacom",
  "orgName": "grafanacom",
  "type": "grafana",
  "name": "createcloudstack",
  "url": "https://createcloudstack.grafana.net",
  "slug": "createcloudstack",
  "labels": {
    "newkey": "newvalue"
  },
  "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

http
DELETE https://grafana.com/api/instances/<STACK_SLUG>

Responses

The following responses may be returned.

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

Example response:

json
{
  "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

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

Responses

The following responses may be returned.

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

Example response:

json
true

Create Hosted Grafana instance API keys

http
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.

Request Body

NameTypeDescriptionRequired
nameStringName of the API key.Yes
roleStringAccess level/Grafana role for the key. Can be one of the following values: Viewer, Editor, or Admin.Yes
secondsToLiveNumberKey expiration in seconds. If it’s a positive number, an expiration date for the key is set. The key doesn’t expire if it’s null, 0, or is omitted completely (unless api_key_max_seconds_to_live configuration option is set).No

Responses

The following responses may be returned.

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

Example response:

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

List data sources

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

Responses

The following responses may be returned.

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

Example response:

json
{
  "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

http
GET https://grafana.com/api/instances/<STACK_SLUG>/plugins

Responses

The following responses may be returned.

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

Example response:

json
{
  "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

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

Request Body

NameTypeDescriptionRequired
pluginStringName of the plugin, for example, grafana-github-datasource.Yes
versionStringVersion of the plugin to install. Defaults to latest.No

Responses

The following responses may be returned.

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

Example response:

json
{
  "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

http
GET https://grafana.com/api/instances/<STACK_SLUG>/plugins/<PLUGIN>

Responses

The following responses may be returned.

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

Example response:

json
{
  "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

http
POST https://grafana.com/api/instances/<STACK_SLUG>/plugins/<PLUGIN>

Request Body

NameTypeDescriptionRequired
versionStringUpdated version of the plugin.Yes

Responses

The following responses may be returned.

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

Example response:

json
{
  "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

http
DELETE https://grafana.com/api/instances/<STACK_SLUG>/plugins/<PLUGIN>

Responses

The following responses may be returned.

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

Example response:

json
{
  "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.

http
GET https://grafana.com/api/stack-regions

Responses

The following responses may be returned.

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

Example response:

json
{
  "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"
    }
  ]
}

API keys

Caution

Cloud API keys are now deprecated. Use Cloud Access Policies instead.

List API keys

http
GET https://grafana.com/api/orgs/<ORG_SLUG>/api-keys

Responses

The following responses may be returned.

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

Example response:

json
{
  "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

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

Request Body

NameTypeDescriptionRequired
nameStringAPI key nameYes
roleStringPermission level of API key. One of Viewer, Editor, Admin, or MetricsPublisher.Yes

Responses

The following responses may be returned.

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

Example response:

json
{
  "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

http
DELETE https://grafana.com/api/orgs/<ORG_SLUG>/api-keys/<API KEY NAME>

Responses

The following responses may be returned.

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

Example response:

json
true