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.

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

{{< admonition type="note" >}} The rate limit on the Grafana Cloud API endpoint for access policies is 600 per hour. {{< /admonition >}}

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.

{{< admonition type="note" >}} Access policies and tokens must have a unique combination of name, org ID, and region. {{< /admonition >}}

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

This API relies on stack and org IDs, and region:

Stack ID: get from the https://grafana.com/api/orgs/{org}/instances endpoint
Org ID: get from the https://grafana.com/api/orgs/{org} endpoint
Region: get the region of your stack from the https://grafana.com/api/orgs/{org}/instances endpoint or get a list of all the available regions from the https://grafana.com/api/stack-regions 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

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

Request body

| Name | Type | Description | Required | | ------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --- | --- | | name | String | Name of the access policy. It must be 1-255 characters long. Characters can only include lowercase letters from the English alphabet (a-z), numbers (0-9), hyphens (-) and underscores (_). | Yes | | displayName | String | Display name of the access policy, visible in the UI. Set to name if not provided. It must be 1-255 characters long. | No | | No | | scopes | List[String] | List of scopes. | Yes | | realms | List[Realm] | List of realms. | Yes | | conditions | Conditions | A set of criteria that is used to restrict access of the access policy and tokens. | No |

Realm

Name	Type	Description	Required
`type`	String	Type of realm. Can be `org` or `stack`.	Yes
`identifier`	String	The unique identifier of a realm (ID of the org or stack depending on the realm type).	Yes
`labelPolicies`	List[LabelPolicy]	List of label policies. Available only with read permissions for metrics and logs.	No

LabelPolicy

Name	Type	Description	Required
`selector`	String	Label selector.	Yes

Conditions

Name	Type	Description	Required
`allowedSubnets`	List[String]	An array of IP addresses with subnet masks in CIDR notation (both IPv4 or IPv6 are supported) for IP range based access control.	Yes

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.

Code	Description
`200`	Successful 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"
}

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.

http

GET https://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. If you omit the `pageCursor` parameter, or provide an empty `pageCursor` value, you receive the first page.	No
`region`	String	Query. 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
`status`	String	Query. 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.

Code	Description
`200`	Successful 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"
    }
  }
}

Code	Description
`400`	Bad request
`401`	API 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

Name	Type	Description	Required
`region`	String	Query. 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
`accessPolicyId`	String	UUID. Path. ID of the access policy.	Yes

Responses

The following responses may be returned.

Code	Description
`200`	Successful 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"
}

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.

{{< admonition type="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

Name	Type	Description	Required
`region`	String	Query. 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
`accessPolicyId`	String	(`UUID`). Path. ID of the access policy.	Yes

Request body

The request body specifies the revised access policy.

| Name | Type | Description | Required | | ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | --- | --- | | displayName | String | Display name of the access policy, visible in the UI. It must be 1-255 characters long. | No | | No | | scopes | List[String] | List of scopes. | Yes | | realms | List[Realm] | List of realms. | Yes | | conditions | Conditions | A set of criteria that is used to restrict access of the access policy and tokens. Providing an empty object {} results in the complete removal of conditions. | No | | status | String | The status of the access policy. Must be active or inactive. | No |

Realm

Name	Type	Description	Required
`type`	String	Type of realm. Can be `org` or `stack`.	Yes
`identifier`	String	The unique identifier of a realm (ID of the org or stack depending on the realm type).	Yes
`labelPolicies`	List[LabelPolicy]	List of label policies. Available only with read permissions for metrics and logs.	No

LabelPolicy

Name	Type	Description	Required
`selector`	String	Label selector.	Yes

Conditions

Name	Type	Description	Required
`allowedSubnets`	List[String]	An array of IP addresses with subnet masks in CIDR notation (both IPv4 or IPv6 are supported) for IP range based access control.	Yes

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.

Code	Description
`200`	Successful 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"
}

Code	Description
`400`	Bad request
`401`	API 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

Name	Type	Description	Required
`region`	String	Query. 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
`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.

http

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

Parameters

Name	Type	Description	Required
`region`	String	Query. 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.

Name	Type	Description	Required
`name`	String	Name of the access policy. It must be 1-255 characters long. Characters can only include lowercase letters from the English alphabet (a-z), numbers (0-9), hyphens (-) and underscores (_).	Yes
`displayName`	String	Display name of the token, visible in the UI. Set to `name` if not provided. It must be 1-255 characters long.	No
`accessPolicyId`	String	ID of the access policy to create the token for.	Yes
`expiresAt`	String	Token expiration date. The token does not expire if this is not provided.	No

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.

Code	Description
`200`	Successful 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"
}

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.

http

GET https://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 the 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. If you omit the `pageCursor` parameter, or provide an empty `pageCursor` value, you receive the first page.	No
`region`	String	Query. 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
`accessPolicyStatus`	String	Query. 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.

Code	Description
`200`	Successful 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"
    }
  }
}

Code	Description
`400`	Bad request
`401`	API 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

Name	Type	Description	Required
`region`	String	Query. 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
`tokenId`	String	(`UUID`). Path. ID of the Token.	Yes

Responses

The following responses may be returned.

Code	Description
`200`	Successful 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"
}

Code	Description
`400`	Bad request
`401`	API 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

Name	Type	Description	Required
`region`	String	Query. 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
`tokenId`	String	(`UUID`). Path. ID of the Token.	Yes

Request body

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

Name	Type	Description	Required
`displayName`	String	Display name of the token, visible in the UI. It must be 1-255 characters long.	No
`expiresAt`	String	Token expiration date (in ISO8601 UTC format). The token does not expire if this field is set to `null`.	No

Example request:

json

{
  "displayName": "My token",
  "expiresAt": "2022-06-09T04:43:16.296Z"
}

Responses

The following responses may be returned.

Code	Description
`200`	Successful 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"
}

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

Delete a token

Remove a specified token with the DELETE method.

http

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

Parameters

Name	Type	Description	Required
`region`	String	Query. 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
`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

Stacks

{{< admonition type="note" >}} Grafana Cloud Free includes 1 stack and Grafana Cloud Pro includes up to 3 stacks. Reach out to support about a Grafana Cloud contracted plan if you would like to add additional stacks to your account. {{< /admonition >}}

List stacks

http

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:

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

Get a stack's connectivity info

http

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

Responses

The following responses may be returned.

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

Example response:

json

{
  "privateConnectivityInfo": {
    "tenants": [
      {
        "type": "prometheus",
        "id": 1899232,
        "info": {
          "privateDNS": "cortex-prod-13-cortex-gw.us-east-2.vpce.grafana.net",
          "serviceName": "com.amazonaws.vpce.us-east-2.vpce-svc-0d13a270cd91a0a3a"
        },
        "ipAllowListCNAME": "src-ips.prometheus-prod-13-prod-us-east-0.grafana.net"
      },
      {
        "type": "graphite",
        "id": 1899233,
        "info": {
          "privateDNS": "cortex-prod-13-cortex-gw.us-east-2.vpce.grafana.net",
          "serviceName": "com.amazonaws.vpce.us-east-2.vpce-svc-0d13a270cd91a0a3a"
        },
        "ipAllowListCNAME": "src-ips.prometheus-prod-13-prod-us-east-0.grafana.net"
      },
      {
        "type": "logs",
        "id": 1048899,
        "info": {
          "privateDNS": "loki-prod-006-cortex-gw.us-east-2.vpce.grafana.net",
          "serviceName": "com.amazonaws.vpce.us-east-2.vpce-svc-071e7d98821c1698b"
        },
        "ipAllowListCNAME": "src-ips.logs-prod-006.grafana.net"
      },
      {
        "type": "traces",
        "id": 1043214,
        "info": {
          "privateDNS": "tempo-prod-04-cortex-gw.us-east-2.vpce.grafana.net",
          "serviceName": "com.amazonaws.vpce.us-east-2.vpce-svc-0a830aaea99ecfc91"
        },
        "ipAllowListCNAME": "src-ips.tempo-prod-04-prod-us-east-0.grafana.net"
      },
      {
        "type": "profiles",
        "id": 1091120,
        "info": {
          "privateDNS": "profiles-prod-001-cortex-gw.us-east-2.vpce.grafana.net",
          "serviceName": "com.amazonaws.vpce.us-east-2.vpce-svc-079d447d0143b24e7"
        },
        "ipAllowListCNAME": "src-ips.profiles-prod-001.grafana.net"
      },
      {
        "type": "alerts",
        "id": 947554,
        "ipAllowListCNAME": "src-ips.alertmanager-prod-us-east-0.grafana.net"
      },
      {
        "type": "grafana",
        "id": 1091120,
        "ipAllowListCNAME": null
      }
    ],
    "otlp": {
      "privateDNS": "prod-us-east-0-otlp-gateway.us-east-2.vpce.grafana.net",
      "serviceName": "com.amazonaws.vpce.us-east-2.vpce-svc-0d36af67949f874c4"
    },
    "pdc": {
      "api": {
        "privateDNS": "private-datasource-connect-api.us-east-2.vpce.grafana.net",
        "serviceName": "com.amazonaws.vpce.us-east-2.vpce-svc-0078cfdaab047fc37"
      },
      "gateway": {
        "privateDNS": "private-datasource-connect.us-east-2.vpce.grafana.net",
        "serviceName": "com.amazonaws.vpce.us-east-2.vpce-svc-032570426402bc97e"
      }
    }
  },
  "influxUrl": "https://influx-prod-13-prod-us-east-0.grafana.net",
  "otlpHttpUrl": "https://otlp-gateway-prod-us-east-0.grafana.net",
  "oncallApiUrl": "https://oncall-prod-us-east-0.grafana.net/oncall",
  "appPlatform": {
    "url": "https://app-platform-apiserver-prod-us-east-0.grafana.net",
    "caData": "<SOME-VERY-LONG-PUBLIC-KEY>"
  }
}

That endpoint contains the way to connect to the various tenants the stack has, including AWS PrivateLink if the region is AWS.

Create stack

{{< admonition type="note" >}} This POST request accepts lowercase characters only. {{< /admonition >}}

http

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 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
`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, refer to List regions. If you don't specify a region, the default is `us`.	No
`description`	String	A short text that describes the purpose of the stack.	No
`labels`	map[String]String	Add 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
`deleteProtection`	Boolean	Prevents the stack from being accidentally deleted. When set to true, delete operations on the stack are blocked until this protection is disabled. Recommended for production or critical environments.	No

{{< admonition type="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. {{< /admonition >}}

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:

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,
  "deleteProtection": true,
  "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

{{< admonition type="note" >}} This POST request accepts lowercase characters only. {{< /admonition >}}

http

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

Request Body

Name	Type	Description	Required
`description`	String	A short text that describes the purpose of the stack.	No
`labels`	map[String]String	Updates 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
`name`	String	Name of stack. Conventionally matches the URL of the instance. For example, `<STACK_SLUG>.grafana.net`.	No
`deleteProtection`	Boolean	Enables or disables delete protection for the stack. When set to true, it prevents the stack from being accidentally deleted. To allow deletion, set this to false.	No

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:

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,
  "deleteProtection": true,
  "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.

Code	Description
`200`	Successful operation.
`401`	API token is missing or invalid.
`404`	Cloud Stack not found.
`409`	Delete protection is enabled.

{{< admonition type="caution" >}} If you receive a 409 response code, it means the stack has delete protection enabled. You must first disable the deleteProtection flag for the stack before you can successfully delete it. {{< /admonition >}}

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,
  "deleteProtection": false,
  "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.

Code	Description
`200`	Successful operation
`401`	API token is missing or invalid.
`404`	Cloud 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

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

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

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.

Code	Description
`200`	Successful operation.
`401`	API token is missing or invalid.
`404`	Cloud Stack not found.
`409`	Conflicting operation, another operation is already in progress.

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.

Code	Description
`200`	Successful operation.
`401`	API token is missing or invalid.
`404`	Cloud Stack not found.
`409`	Conflicting operation, another operation is already in progress.

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

Name	Type	Description	Required
`plugin`	String	Name of the plugin, for example, `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`	Conflicting operation, another operation is already in progress.

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.

Code	Description
`200`	Successful operation.
`401`	API token is missing or invalid.
`404`	Plugin or Cloud Stack not found.
`409`	Conflicting operation, another operation is already in progress.

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

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`	Conflicting operation, another operation is already in progress.

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.

Code	Description
`200`	Successful operation.
`401`	API token is missing or invalid.
`404`	Plugin or Cloud Stack not found.
`409`	Conflicting operation, another operation is already in progress.

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.

Code	Description
`200`	Successful operation.
`401`	API token is missing or invalid.
`409`	Conflicting operation, another operation is already in progress.

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

{{< admonition type="caution" >}} Cloud API keys are now deprecated. Use Cloud Access Policies instead. {{< /admonition >}}

List API keys

http

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:

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

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:

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.

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

Example response:

json

true

Billed usage

This API makes it possible to fetch billed usage broken down by stack for a specified year and month.

Get billed usage

http

GET https://grafana.com/api/orgs/<ORG_SLUG>/billed-usage?month=<MONTH>&year=<YEAR>

Parameters

Name	Type	Description	Required
`month`	Query	numeric value for the month to retrieve billed usage for	yes
`year`	Query	numeric value for the year to retrieve billed usage for	yes

Responses

The following responses may be returned.

Code	Description
`200`	Successful operation.
`401`	API token is missing or invalid.
`403`	Forbidden.
`404`	Not found.
`409`	Wrong or missing parameters.

Example response:

json

{
  "items": [
    {
      "id": 1111198068,
      "dimensionId": "hl",
      "dimensionName": "Logs",
      "unit": "GB",
      "includedUsage": 50,
      "totalUsage": 251.02109133593612,
      "overage": 201,
      "orgRates": {
        "tiers": [
          {
            "min": 50,
            "rate": 0.5
          }
        ]
      },
      "amountDue": 100.5,
      "periodStart": "2024-09-01T00:00:00Z",
      "periodEnd": "2024-09-30T23:59:59Z",
      "description": "Hosted Logs Usage - September 2024",
      "notes": "Per-instance Usage\n - example-logs - Usage: 251.021GB\n\nIncluded Usage: 50GB\nTotal Usage: 251.021GB\nUsage in excess of 50GB: 201GB @ $0.5/GB = $100.50\nTotal Usage Amount: $100.50",
      "usages": [
        {
          "id": 1111163428,
          "stackId": 111118,
          "periodStart": "2024-09-01T00:00:00Z",
          "periodEnd": "2024-09-30T23:59:59Z",
          "totalUsage": 251.02109133593612,
          "isProrated": false,
          "ingestUsage": 251.02109133593612,
          "queryUsage": 1255.8636820528654,
          "stackName": "example.grafana.net",
          "stackLabels": {}
        }
      ]
    },
    {
      "id": 2222297587,
      "dimensionId": "hm",
      "dimensionName": "Metrics",
      "unit": "series",
      "includedUsage": 10000,
      "totalUsage": 129755.72,
      "overage": 119756,
      "orgRates": {
        "tiers": [
          {
            "min": 10000,
            "rate": 6.5
          }
        ],
        "includedDPM": 1
      },
      "amountDue": 778.41,
      "periodStart": "2024-09-01T00:00:00Z",
      "periodEnd": "2024-09-30T23:59:59Z",
      "description": "Hosted Metrics Usage - September 2024",
      "notes": "Per-instance Usage\n - example-prom - Series: 55937, DPM: 132364, Usage: 132364\n   Usage pro-rated 2024-09-01 - 2024-09-30: 129756\n\nIncluded Usage: 10000\nTotal Usage: 129756\nUsage in excess of 10000: 119756 @ $6.50/1000 = $778.41\nTotal Usage Amount: $778.41",
      "usages": [
        {
          "id": 1111162008,
          "stackId": 111118,
          "periodStart": "2024-09-01T00:00:00Z",
          "periodEnd": "2024-09-30T23:59:59Z",
          "totalUsage": 129755.72,
          "isProrated": false,
          "activeSeries": 55937,
          "dpm": 132364,
          "stackName": "example.grafana.net",
          "stackLabels": {}
        }
      ]
    },
    {
      "id": 1111195084,
      "dimensionId": "hg",
      "dimensionName": "Grafana Users",
      "unit": "user",
      "includedUsage": 3,
      "totalUsage": 14,
      "overage": 11,
      "orgRates": {
        "tiers": [
          {
            "min": 3,
            "rate": 8
          }
        ]
      },
      "amountDue": 88,
      "periodStart": "2024-09-01T00:00:00Z",
      "periodEnd": "2024-09-30T23:59:59Z",
      "description": "Hosted Grafana Usage - September 2024",
      "notes": "Per-instance Usage\n - example.grafana.net - Total Unique Users: 14\n\nIncluded Users: 3\nTotal Unique Users: 14\nUsers in excess of 3: 11 @ $8/User = $88.00\nTotal Usage Amount: $88.00",
      "usages": [
        {
          "id": 1111157272,
          "stackId": 111118,
          "periodStart": "2024-09-01T00:00:00Z",
          "periodEnd": "2024-09-30T23:59:59Z",
          "totalUsage": 14,
          "isProrated": false,
          "grafanaUsage": 14,
          "onCallUsage": 0,
          "stackName": "example.grafana.net",
          "stackLabels": {}
        }
      ]
    }
  ]
}