Grafana Cloud API

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:

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.

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. Will be 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:

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

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

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:

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

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:

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

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 ({}).

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:

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

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

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.

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. Will be 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 will not expire if this is not provided.	No

Example request:

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

Responses

The following responses may be returned.

Code	Description
`200`	Successful operation

Example response:

{
  "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "name": "mytoken",
  "displayName": "My Token",
  "expiresAt": "2022-06-08T22:05:46.959Z",
  "firstUsedAt": "2022-06-08T22:05:46.959Z",
  "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.

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:

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

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:

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

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

Example request:

{
  "displayName": "My token"
}

Responses

The following responses may be returned.

Code	Description
`200`	Successful operation

Example response:

{
  "id": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
  "name": "mytoken",
  "displayName": "My token",
  "expiresAt": "2022-06-09T04:43:16.296Z",
  "firstUsedAt": "2022-06-09T04:43:16.296Z",
  "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

Delete a token

Remove a specified token with the DELETE method.

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

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

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

Responses

The following responses may be returned.

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

Example response:

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

Create stack

Note
This POST request accepts lowercase characters only.

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

Request Body

Name	Type	Description	Required
`name`	String	Name of stack. Conventionally matches the URL of the instance. For example, `<STACK_SLUG>.grafana.net`.	Yes
`slug`	String	Subdomain that the Grafana instance 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

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

Responses

The following responses may be returned.

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

Example response:

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

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

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

Responses

The following responses may be returned.

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

Example response:

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

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

Responses

The following responses may be returned.

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

Example response:

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

Restart Grafana

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

Responses

The following responses may be returned.

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

Example response:

true

Create Hosted Grafana instance API keys

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

This creates API keys specific to use for managing your hosted Grafana instance. This is different from Grafana Cloud API keys created for Grafana Cloud operations.

This endpoint requires the Admin role.

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:

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

List data sources

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

Responses

The following responses may be returned.

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

Example response:

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

Grafana plugins

The API allows managing plugins installed on your hosted Grafana instances.

You can discover plugins in the Grafana Plugins Directory.

List plugins installed on an instance

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

Responses

The following responses may be returned.

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

Example response:

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

Add a plugin to instance

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

Request Body

Name	Type	Description	Required
`plugin`	String	Name of the plugin, 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:

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

Get installed plugin info

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

Responses

The following responses may be returned.

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

Example response:

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

Update installed plugin version

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

Request Body

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

Responses

The following responses may be returned.

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

Example response:

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

Delete an installed plugin

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

Responses

The following responses may be returned.

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

Example response:

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

Regions

List regions

Use the following call to retrieve a list of regions to specify when you create a stack.

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

Responses

The following responses may be returned.

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

Example response:

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

API keys

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

List API keys

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

Responses

The following responses may be returned.

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

Example response:

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

Create API key

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

Request Body

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

Responses

The following responses may be returned.

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

Example response:

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

Delete API key

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

Responses

The following responses may be returned.

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

Example response:

true

Billed usage

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

Get billed usage

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:

{
  "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": 8
          }
        ],
        "includedDPM": 1
      },
      "amountDue": 958.05,
      "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 @ $8/1000 = $958.05\nTotal Usage Amount: $958.05",
      "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": {}
        }
      ]
    }
  ]
}

Was this page helpful?

Email docs@grafana.com

Help and support

Community