The Grafana Cloud API, sometimes referred to as the Grafana.com API or GCOM API, allows you to interact with resources from your Grafana Cloud Stack programmatically.
Below is the list of approved, static endpoints and calls for general use. Any other paths are subject to change and are not maintained for general user consumption.
Note
If you need to manage or access resources from your Grafana instance—such as dashboards, alerts, data sources, users, and more—refer to the HTTP API instead.
Authentication
You must create a Cloud Access Policy and token to use the Cloud API.
To create a Grafana Cloud Access Policy, refer to Create an access policy.
Requests to the API are authenticated using the Authorization header:
http
Authorization:Bearer <CLOUD ACCESS POLICY TOKEN>
Access policies and tokens
Access policies and tokens use access policy, token, scope, realm, labelselector and conditions resources.
For more information about these resources, refer to Grafana Cloud Access Policies.
Note
Access policies and tokens must have a unique combination of name, org ID, and region.
All API requests must specify a token in the request’s Authorization header.
This API relies on stack and org IDs.
You can get your stack ID from the https://grafana.com/api/orgs/{org}/instances endpoint.
You can get your org ID from the https://grafana.com/api/orgs/{org} endpoint.
Paginated endpoints optionally accept both pageSize and pageCursor query parameters.
If you omit the pageCursor parameter, or provide an empty pageCursor value, you receive the first page.
You can get the next page’s URL the current page’s metadata.pagination.nextPage property.
If that field is null, you’ve reached the last page and there are no records left.
Create an access policy
Create an access policy with the POST method.
http
POST https://www.grafana.com/api/v1/accesspolicies
Parameters
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.
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.
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.
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.
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.
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. 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.
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.
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.
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.
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
http
GET https://grafana.com/api/orgs/<ORG_SLUG>/instances
This POST request accepts lowercase characters only.
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
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.
This POST request accepts lowercase characters only.
http
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.
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).
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"}]}