Grafana Cloud API
The Grafana Cloud API is sometimes referred to as the Grafana.com API or the Gcom API. It is a work in progress, however the following calls and paths on this page are static and approved for general use. If you hear of other paths and calls, know that they are subject to change and not generally maintained for user consumption.
Authentication
You must create a Cloud Access Policy and token to use the Cloud API. Refer to Create a Grafana Cloud Access Policy for more information.
Requests to the API are authenticated using the Authorization
header:
Authorization: Bearer <Cloud Access Policy token>
Access policies and tokens
This section describes endpoints used to manage the resources for authentication and authorization.
Access policies and tokens use access policy
, token
, scope
, realm
, labelselector
and conditions
resources.
For more information about these resources, refer to the Grafana Cloud Access Policies documentation.
All API requests must specify a token in the request’s Authorization
header.
This API relies on stack and org IDs.
Your stack IDs can be obtained from https://grafana.com/api/orgs/{org}/instances
and your org ID can be obtained from https://grafana.com/api/orgs/{org}
.
Paginated endpoints optionally accept both pageSize
and pageCursor
query parameters.
If pageCursor
is not provided or empty, the first page will be requested.
The next page’s URL can be obtained from the current page’s metadata.pagination.nextPage
property.
If that field is null
, you’ve reached the last page and there are no records left.
Note
Access policies and tokens must have a unique combination of name, org ID, and region.
Create an access policy
Create an access policy with the POST
method.
POST http://www.grafana.com/api/v1/accesspolicies
Parameters
Name | Type | Description | Required |
---|---|---|---|
region | String | Region where the API is deployed. Generally where the stack is deployed. | Yes |
Request body
Example request:
{
"name": "stack-readers",
"displayName": "Stack Readers",
"scopes": ["metrics:read", "logs:read", "traces:read", "alerts:read"],
"realms": [
{
"type": "stack",
"identifier": "123",
"labelPolicies": [
{
"selector": "{env != \"dev\"}"
}
]
}
],
"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 http://www.grafana.com/api/v1/accesspolicies
Parameters
Name | Type | Description | Required |
---|---|---|---|
name | Query | Name of the access policy to filter by. | No |
realmType | String | Query. Available values are org and stack . | No |
realmIdentifier | String | Requires realmType. Identifier of the realm. | No |
pageSize | String | The number of records to be returned per page. The default value is 500; the maximum value is 500. | No |
pageCursor | String | Query. A cursor used for paging through the results. The first page will be fetched when not provided. | No |
region | String | Query. Region where the API is deployed. Generally where the stack is deployed. Available values are us , eu , and au . | Yes |
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 http://www.grafana.com/api/v1/accesspolicies/{accessPolicyID}
Parameters
Name | Type | Description | Required |
---|---|---|---|
region | String | Query. Region where the API is deployed. Generally where the stack is deployed. Available values are us , eu , and au . | Yes |
accessPolicyId | String | ($uuid). Path. ID of the access policy. | Yes |
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation |
Example response:
{
"id": "c45485b6-8321-4cf2-bcec-12006df755ff",
"orgId": "1",
"name": "stack-readers",
"displayName": "Stack Readers",
"scopes": ["metrics:read", "logs:read", "traces:read", "alerts:read"],
"realms": [
{
"type": "stack",
"identifier": "123",
"labelPolicies": [
{
"selector": "{env != \"dev\"}"
}
]
}
],
"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
tonull
or to an empty object ({}
).
POST http://www.grafana.com/api/v1/accesspolicies/{accessPolicyId}
Parameters
Name | Type | Description | Required |
---|---|---|---|
region | String | Query. Region where the API is deployed. Generally where the stack is deployed. Available values are us , eu , and au . | Yes |
accessPolicyId | String | (UUID ). Path. ID of the access policy. | Yes |
Request body
The request body specifies the revised access policy.
Example request:
{
"displayName": "Stack Readers",
"scopes": ["metrics:read", "logs:read", "traces:read", "alerts:read"],
"realms": [
{
"type": "stack",
"identifier": "123",
"labelPolicies": [
{
"selector": "{env != \"dev\"}"
}
]
}
],
"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 http://www.grafana.com/api/v1/accesspolicies/{accessPolicyId}
Parameters
Name | Type | Description | Required |
---|---|---|---|
region | String | Query. Region where the API is deployed. Generally where the stack is deployed. Available values are us , eu , and au . | Yes |
accessPolicyId | String | (UUID ). Path. ID of the access policy. | Yes |
Responses
The following responses may be returned.
Code | Description |
---|---|
204 | Access policy deleted successfully. |
400 | Bad request |
401 | API token is missing or invalid |
Create a token
Create a token with the POST
method.
POST http://www.grafana.com/api/v1/tokens
Parameters
Name | Type | Description | Required |
---|---|---|---|
region | String | Query. Region where the API is deployed. Generally where the stack is deployed. Available values are us , eu , and au . | Yes |
Request body
The request body contains details about the token being created.
Example request:
{
"accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
"name": "mytoken",
"displayName": "My Token",
"expiresAt": "2022-06-08T22:05:46.958Z"
}
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation |
Example response:
{
"id": "c45485b6-8321-4cf2-bcec-12006df755ff",
"accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
"name": "mytoken",
"displayName": "My Token",
"expiresAt": "2022-06-08T22:05:46.959Z",
"firstUsedAt": "2022-06-08T22:05:46.959Z",
"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 http://www.grafana.com/api/v1/tokens
Parameters
Name | Type | Description | Required |
---|---|---|---|
accessPolicyId | String | Query. ID of the access policy to filter by. | No |
accessPolicyName | String | Query. Name of the access policy to filter by. | No |
accessPolicyRealmType | String | Query. Type of the access policy realm. Available values are org and stack . | No |
accessPolicyRealmIdentifier | String | Query. Identifier of the access policy realm. Requires accessPolicyRealmType. | No |
name | String | Query. Name of the Token to filter by. | No |
expiresBefore | String | Query. Time (in ISO8601 UTC format) to filter tokens that have expiresAt set before the given time. | No |
expiresAfter | String | Query. Time (in ISO8601 UTC format) to filter tokens that have expiresAt set after te given time. | No |
pageSize | String | Query. The number of records to be returned per page. Default value is 500 ; the maximum value is 500 . | No |
pageCursor | String | Query. A cursor used for paging through the results. The first page will be fetched when not provided. | No |
region | String | Query. Region where the API is deployed. Generally where the stack is deployed. Available values are us , eu , and au . | Yes |
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 http://www.grafana.com/api/v1/tokens/{tokenId}
Parameters
Name | Type | Description | Required |
---|---|---|---|
region | String | Query. Region where the API is deployed. Generally where the stack is deployed. Available values are us , eu , and au . | Yes |
tokenId | String | (UUID ). Path. ID of the Token. | Yes |
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation |
Example response:
{
"id": "c45485b6-8321-4cf2-bcec-12006df755ff",
"accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
"name": "mytoken",
"displayName": "My Token",
"expiresAt": "2022-06-09T04:31:23.559Z",
"firstUsedAt": "2022-06-09T04:31:23.559Z",
"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 http://www.grafana.com/api/v1/tokens/{tokenId}
Parameters
Name | Type | Description | Required |
---|---|---|---|
region | String | Query. Region where the API is deployed. Generally where the stack is deployed. Available values are us , eu , and au . | Yes |
tokenId | String | (UUID ). Path. ID of the Token. | Yes |
Request body
The request body contains the updated values being applied to the token.
Example request:
{
"displayName": "My token"
}
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation |
Example response:
{
"id": "c45485b6-8321-4cf2-bcec-12006df755ff",
"accessPolicyId": "c45485b6-8321-4cf2-bcec-12006df755ff",
"name": "mytoken",
"displayName": "My token",
"expiresAt": "2022-06-09T04:43:16.296Z",
"firstUsedAt": "2022-06-09T04:43:16.296Z",
"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 http://www.grafana.com/api/v1/tokens/{tokenId}
Parameters
Name | Type | Description | Required |
---|---|---|---|
region | String | Query. Region where the API is deployed. Generally where the stack is deployed. Available values are us , eu , and au . | Yes |
tokenId | String | (UUID ). Path. ID of the Token. | Yes |
Responses
The following responses may be returned.
Code | Description |
---|---|
204 | Token deleted successfully |
400 | Bad request |
401 | API token is missing or invalid |
Stacks
Note
Grafana Cloud Free includes 1 stack and Grafana Cloud Pro includes up to 3 stacks. Reach out to us about Grafana Cloud Advanced if you would like to add additional stacks to your account.
List stacks
GET https://grafana.com/api/orgs/<org_slug>/instances
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
403 | Forbidden. |
Example response:
{
"items": [
{
"id": 007303,
"orgId": 052992,
"orgSlug": "grafanacom",
"orgName": "grafanacom",
"type": "grafana",
"name": "cloudapistack.grafana.net",
"url": "https://cloudapistack.grafana.net",
"slug": "cloudapistack",
"version": "stable",
"description": "",
"status": "active",
"gateway": "istio",
"createdAt": "2023-01-04T06:43:24.000Z",
"createdBy": "foobar",
"updatedAt": null,
"updatedBy": "",
"trial": 0,
"trialExpiresAt": null,
"clusterId": 69,
"clusterSlug": "prod-us-central-0",
"clusterName": "prod-us-central-0",
"plan": "gcloud",
"planName": "Grafana Cloud",
"billingStartDate": "2023-01-04T06:43:23.000Z",
"billingEndDate": null,
"billingActiveUsers": 0,
"billingGrafanaActiveUsers": 0,
"billingOnCallActiveUsers": 0,
"currentActiveUsers": 0,
"currentActiveAdminUsers": 0,
"currentActiveEditorUsers": 0,
"currentActiveViewerUsers": 0,
"dailyUserCnt": 0,
"dailyAdminCnt": 0,
"dailyEditorCnt": 0,
"dailyViewerCnt": 0,
"dashboardCnt": 8,
"datasourceCnts": {},
"userQuota": 10,
"dashboardQuota": -1,
"alertQuota": -1,
"alertCnt": 0,
"ssl": true,
"customAuth": true,
"customDomain": true,
"support": true,
"runningVersion": "9.3.2-45365 (commit: ef5286dd77, branch: v9.3.x)",
"machineLearning": 0,
"incident": 0,
"hmInstancePromId": 715391,
"hmInstancePromUrl": "https://prometheus-us-central1.grafana.net",
"hmInstancePromName": "cloudapistack-prom",
"hmInstancePromStatus": "active",
"hmInstancePromCurrentUsage": 0,
"hmInstancePromCurrentActiveSeries": 0,
"hmInstanceGraphiteId": 715392,
"hmInstanceGraphiteUrl": "https://graphite-prod-10-prod-us-central-0.grafana.net",
"hmInstanceGraphiteName": "cloudapistack-graphite",
"hmInstanceGraphiteType": "graphite-v5",
"hmInstanceGraphiteStatus": "active",
"hmInstanceGraphiteCurrentUsage": 0,
"hlInstanceId": 356665,
"hlInstanceUrl": "https://logs-prod-017.grafana.net",
"hlInstanceName": "cloudapistack-logs",
"hlInstanceStatus": "active",
"hlInstanceCurrentUsage": 0,
"amInstanceId": 355647,
"amInstanceName": "cloudapistack-alerts",
"amInstanceUrl": "https://alertmanager-us-central1.grafana.net",
"amInstanceStatus": "active",
"amInstanceGeneratorUrl": "https://cloudapistack.grafana.net",
"amInstanceGeneratorUrlDatasource": "",
"htInstanceId": 353178,
"htInstanceUrl": "https://tempo-us-central1.grafana.net",
"htInstanceName": "cloudapistack-traces",
"htInstanceStatus": "active",
"regionId": 1,
"regionSlug": "us",
"links": [
{
"rel": "self",
"href": "/instances/cloudapistack"
},
{
"rel": "org",
"href": "/orgs/grafanacom"
},
{
"rel": "plugins",
"href": "/instances/cloudapistack/plugins"
}
]
}
],
"orderBy": "name",
"direction": "asc",
"total": 1,
"pages": 1,
"pageSize": 1000000,
"page": 1,
"links": [
{
"rel": "self",
"href": "/instances"
}
]
}
Create stack
Note
This POST request accepts lowercase characters only.
POST https://grafana.com/api/instances
Request Body
Name | Type | Description | Required |
---|---|---|---|
name | String | Name of stack. Conventionally matches the URL of the instance. For example, <stack_slug>.grafana.net . | Yes |
slug | String | Subdomain that the Grafana instance will be available at. For example, if you set the slug to <stack_slug> , the instance will be available at https://<stack_slug>.grafana.net . | Yes |
url | String | If you use a custom domain for the instance, you must provide it here. For example, “https://grafana.yourdoman.io” . | No |
region | String | Choose a region for your stack. For example, you can specify the United States (us ) or Europe (eu ). Use the GET /api/stack-regions endpoint to see a list of regions to choose from. For more information, see List regions. If you don’t specify a region, the default is us . | No |
Note
For the custom domain, you must set up aCNAME
record that points to<stack_slug>.grafana.net
before you can specify the domain.
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
403 | Forbidden. |
409 | Conflict. |
Example response:
{
"id": 507363,
"orgId": 652992,
"orgSlug": "grafanacom",
"orgName": "grafanacom",
"type": "grafana",
"name": "createcloudstack",
"url": "https://createcloudstack.grafana.net",
"slug": "createcloudstack",
"version": "stable",
"description": "",
"status": "active",
"gateway": "istio",
"createdAt": "2023-01-04T08:20:07.000Z",
"createdBy": "testengineer",
"updatedAt": null,
"updatedBy": "",
"trial": 0,
"trialExpiresAt": null,
"clusterId": 69,
"clusterSlug": "prod-us-central-0",
"clusterName": "prod-us-central-0",
"plan": "gcloud",
"planName": "Grafana Cloud",
"billingStartDate": "2023-01-04T08:20:06.000Z",
"billingEndDate": null,
"billingActiveUsers": 0,
"billingGrafanaActiveUsers": 0,
"billingOnCallActiveUsers": 0,
"currentActiveUsers": 0,
"currentActiveAdminUsers": 0,
"currentActiveEditorUsers": 0,
"currentActiveViewerUsers": 0,
"dailyUserCnt": 0,
"dailyAdminCnt": 0,
"dailyEditorCnt": 0,
"dailyViewerCnt": 0,
"dashboardCnt": 0,
"datasourceCnts": {},
"userQuota": 10,
"dashboardQuota": -1,
"alertQuota": -1,
"alertCnt": 0,
"ssl": true,
"customAuth": true,
"customDomain": true,
"support": true,
"runningVersion": "",
"machineLearning": 0,
"incident": 0,
"hmInstancePromId": 715511,
"hmInstancePromUrl": "https://prometheus-us-central1.grafana.net",
"hmInstancePromName": "createcloudstack-prom",
"hmInstancePromStatus": "active",
"hmInstancePromCurrentUsage": 0,
"hmInstancePromCurrentActiveSeries": 0,
"hmInstanceGraphiteId": 715512,
"hmInstanceGraphiteUrl": "https://graphite-prod-10-prod-us-central-0.grafana.net",
"hmInstanceGraphiteName": "createcloudstack-graphite",
"hmInstanceGraphiteType": "graphite-v5",
"hmInstanceGraphiteStatus": "active",
"hmInstanceGraphiteCurrentUsage": 0,
"hlInstanceId": 356725,
"hlInstanceUrl": "https://logs-prod-017.grafana.net",
"hlInstanceName": "createcloudstack-logs",
"hlInstanceStatus": "active",
"hlInstanceCurrentUsage": 0,
"amInstanceId": 355707,
"amInstanceName": "createcloudstack-alerts",
"amInstanceUrl": "https://alertmanager-us-central1.grafana.net",
"amInstanceStatus": "active",
"amInstanceGeneratorUrl": "https://createcloudstack.grafana.net",
"amInstanceGeneratorUrlDatasource": "",
"htInstanceId": 353238,
"htInstanceUrl": "https://tempo-us-central1.grafana.net",
"htInstanceName": "createcloudstack-traces",
"htInstanceStatus": "active",
"regionId": 1,
"regionSlug": "us",
"links": [
{
"rel": "self",
"href": "/instances/createcloudstack"
},
{
"rel": "org",
"href": "/orgs/grafanacom"
},
{
"rel": "plugins",
"href": "/instances/createcloudstack/plugins"
}
]
}
Delete stack
DELETE https://grafana.com/api/instances/<stack_slug>
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
404 | Cloud Stack not found. |
Example response:
{
"id": 507366,
"orgId": 652992,
"orgSlug": "grafanacom",
"orgName": "grafanacom",
"type": "grafana",
"name": "createcloudstack",
"url": "https://createcloudstack.grafana.net",
"slug": "createcloudstack",
"version": "stable",
"description": "",
"status": "deleted",
"gateway": "istio",
"createdAt": "2023-01-04T08:22:00.000Z",
"createdBy": "ishanjain",
"updatedAt": "2023-01-04T08:30:36.066Z",
"updatedBy": "ishanjain",
"trial": 0,
"trialExpiresAt": null,
"clusterId": 69,
"clusterSlug": "prod-us-central-0",
"clusterName": "prod-us-central-0",
"plan": "gcloud",
"planName": "Grafana Cloud",
"billingStartDate": "2023-01-04T08:21:59.000Z",
"billingEndDate": "2023-01-04T08:30:36.066Z",
"billingActiveUsers": 0,
"billingGrafanaActiveUsers": 0,
"billingOnCallActiveUsers": 0,
"currentActiveUsers": 0,
"currentActiveAdminUsers": 0,
"currentActiveEditorUsers": 0,
"currentActiveViewerUsers": 0,
"dailyUserCnt": 0,
"dailyAdminCnt": 0,
"dailyEditorCnt": 0,
"dailyViewerCnt": 0,
"dashboardCnt": 0,
"datasourceCnts": {},
"userQuota": 10,
"dashboardQuota": -1,
"alertQuota": -1,
"alertCnt": 0,
"ssl": true,
"customAuth": true,
"customDomain": true,
"support": true,
"runningVersion": "9.3.2-45365 (commit: ef5286dd77, branch: v9.3.x)",
"machineLearning": 0,
"incident": 0,
"hmInstancePromId": 715517,
"hmInstancePromUrl": "https://prometheus-us-central1.grafana.net",
"hmInstancePromName": "createcloudstack-prom",
"hmInstancePromStatus": "active",
"hmInstancePromCurrentUsage": 0,
"hmInstancePromCurrentActiveSeries": 0,
"hmInstanceGraphiteId": 715518,
"hmInstanceGraphiteUrl": "https://graphite-prod-10-prod-us-central-0.grafana.net",
"hmInstanceGraphiteName": "createcloudstack-graphite",
"hmInstanceGraphiteType": "graphite-v5",
"hmInstanceGraphiteStatus": "active",
"hmInstanceGraphiteCurrentUsage": 0,
"hlInstanceId": 356728,
"hlInstanceUrl": "https://logs-prod-017.grafana.net",
"hlInstanceName": "createcloudstack-logs",
"hlInstanceStatus": "active",
"hlInstanceCurrentUsage": 0,
"amInstanceId": 355710,
"amInstanceName": "createcloudstack1-alerts",
"amInstanceUrl": "https://alertmanager-us-central1.grafana.net",
"amInstanceStatus": "active",
"amInstanceGeneratorUrl": "https://createcloudstack.grafana.net",
"amInstanceGeneratorUrlDatasource": "",
"htInstanceId": 353241,
"htInstanceUrl": "https://tempo-us-central1.grafana.net",
"htInstanceName": "createcloudstack-traces",
"htInstanceStatus": "active",
"regionId": 1,
"regionSlug": "us",
"links": [
{
"rel": "self",
"href": "/instances/507366"
},
{
"rel": "org",
"href": "/orgs/grafanacom"
},
{
"rel": "plugins",
"href": "/instances/507366/plugins"
}
]
}
Restart Grafana
POST https://grafana.com/api/instances/<stack_slug>/restart
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation |
401 | API token is missing or invalid. |
404 | Cloud Stack not found |
Example response:
true
Create Hosted Grafana instance API keys
POST https://grafana.com/api/instances/<stack_slug>/api/auth/keys
This creates API keys specific to use for managing your hosted Grafana instance. This is different from Grafana Cloud API keys created for Grafana Cloud operations.
This endpoint requires the Admin role.
Request Body
Name | Type | Description | Required |
---|---|---|---|
name | String | Name of the API key. | Yes |
role | String | Access level/Grafana role for the key. Can be one of the following values: Viewer , Editor , or Admin . | Yes |
secondsToLive | Number | Key expiration in seconds. If it is a positive number, an expiration date for the key is set. The key will never expire if it is null, zero, or is omitted completely (unless api_key_max_seconds_to_live configuration option is set). | No |
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
404 | Cloud Stack not found. |
409 | Conflict. |
Example response:
{
"id": 1,
"name": "testkey",
"key": "eyJrIjoiMWpSRVhRUVJHZlc3NW1laklzV3htQUt0cUxtS3RuWFUiLCJuIjoidGVzdGtleSIsImlkIjoxf"
}
List data sources
GET https://grafana.com/api/instances/<stack_slug>/datasources
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
404 | Cloud Stack not found. |
409 | Unexpected Parameter (InvalidArgument). |
Example response:
{
"items": [
{
"id": 25744816,
"instanceId": 2860016,
"name": "grafanacloud-usage",
"type": "prometheus",
"access": "proxy",
"grafanaOrgId": 1,
"url": "https://billing.grafana.net/api/prom",
"password": "",
"user": "",
"database": "",
"basicAuth": 1,
"basicAuthUser": "65299211",
"withCredentials": 0,
"isDefault": 0,
"jsonData": {
"timeInterval": "60s",
"timeout": "150",
"prometheusVersion": "2.3.0",
"prometheusType": "Mimir"
},
"version": 1,
"editable": 1,
"delete": 0,
"createdAt": "2023-01-04T08:20:13.484927Z",
"updatedAt": null
},
{
"id": 25744915,
"instanceId": 2860016,
"name": "grafanacloud-createcloudstack-logs",
"type": "loki",
"access": "proxy",
"grafanaOrgId": 1,
"url": "https://logs-prod-017.grafana.net",
"password": "",
"user": "",
"database": "",
"basicAuth": 1,
"basicAuthUser": "3567215",
"withCredentials": 0,
"isDefault": 0,
"jsonData": {
"timeout": "300"
},
"version": 1,
"editable": 1,
"delete": 0,
"createdAt": "2023-01-04T08:20:13.625323Z",
"updatedAt": null
}
]
}
Grafana plugins
The API allows managing plugins installed on your hosted Grafana instances.
You can discover plugins in the Grafana Plugins Directory.
List plugins installed on an instance
GET https://grafana.com/api/instances/<stack_slug>/plugins
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
404 | Cloud Stack not found. |
409 | Unexpected Parameter (InvalidArgument). |
Example response:
{
"items": [
{
"id": 256529,
"instanceId": 507363,
"instanceUrl": "https://createcloudstack.grafana.net",
"pluginId": 663,
"pluginSlug": "grafana-github-datasource",
"pluginName": "GitHub",
"version": "1.3.1",
"latestVersion": "1.3.1",
"createdAt": "2023-01-04T09:33:55.000Z",
"updatedAt": null,
"links": [
{
"rel": "self",
"href": "/instances/507363/plugins/grafana-github-datasource"
},
{
"rel": "instance",
"href": "/instances/507363"
}
]
}
],
"orderBy": "pluginName",
"direction": "asc",
"links": [
{
"rel": "self",
"href": "/instances/createcloudstack/plugins"
}
]
}
Add a plugin to instance
POST https://grafana.com/api/instances/<stack_slug>/plugins
Request Body
Name | Type | Description | Required |
---|---|---|---|
plugin | String | Name of the plugin, e.g., grafana-github-datasource . | Yes |
version | String | Version of the plugin to install. Defaults to latest . | No |
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
404 | Plugin or Cloud Stack not found. |
409 | Unexpected Parameter (InvalidArgument). |
Example response:
{
"id": 256519,
"instanceId": 507363,
"instanceUrl": "https://createcloudstack.grafana.net",
"instanceSlug": "createcloudstack",
"pluginId": 663,
"pluginSlug": "grafana-github-datasource",
"pluginName": "GitHub",
"version": "1.3.1",
"latestVersion": "1.3.1",
"createdAt": "2023-01-04T08:50:42.000Z",
"updatedAt": null,
"links": [
{
"rel": "self",
"href": "/instances/createcloudstack/plugins/grafana-github-datasource"
},
{
"rel": "instance",
"href": "/instances/createcloudstack"
}
]
}
Get installed plugin info
GET https://grafana.com/api/instances/<stack_slug>/plugins/<plugin>
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
404 | Plugin or Cloud Stack not found. |
409 | Unexpected Parameter (InvalidArgument). |
Example response:
{
"id": 256519,
"instanceId": 507363,
"instanceUrl": "https://createcloudstack.grafana.net",
"instanceSlug": "createcloudstack",
"pluginId": 663,
"pluginSlug": "grafana-github-datasource",
"pluginName": "GitHub",
"version": "1.3.1",
"latestVersion": "1.3.1",
"createdAt": "2023-01-04T08:50:42.000Z",
"updatedAt": null,
"links": [
{
"rel": "self",
"href": "/instances/createcloudstack/plugins/grafana-github-datasource"
},
{
"rel": "instance",
"href": "/instances/createcloudstack"
}
]
}
Update installed plugin version
POST https://grafana.com/api/instances/<stack_slug>/plugins/<plugin>
Request Body
Name | Type | Description | Required |
---|---|---|---|
version | String | Updated version of the plugin. | Yes |
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
404 | Plugin or Cloud Stack not found. |
409 | Unexpected Parameter (InvalidArgument). |
Example response:
{
"id": 256519,
"instanceId": 507363,
"instanceUrl": "https://createcloudstack.grafana.net",
"instanceSlug": "createcloudstack",
"pluginId": 663,
"pluginSlug": "grafana-github-datasource",
"pluginName": "GitHub",
"version": "1.3.0",
"latestVersion": "1.3.1",
"createdAt": "2023-01-04T08:50:42.000Z",
"updatedAt": "2023-01-04T08:55:00.088Z",
"links": [
{
"rel": "self",
"href": "/instances/createcloudstack/plugins/grafana-github-datasource"
},
{
"rel": "instance",
"href": "/instances/createcloudstack"
}
]
}
Delete an installed plugin
DELETE https://grafana.com/api/instances/<stack_slug>/plugins/<plugin>
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
404 | Plugin or Cloud Stack not found. |
409 | Unexpected Parameter (InvalidArgument). |
Example response:
{
"id": 256519,
"instanceId": 507363,
"instanceUrl": "https://createcloudstack.grafana.net",
"instanceSlug": "createcloudstack",
"pluginId": 663,
"pluginSlug": "grafana-github-datasource",
"pluginName": "GitHub",
"version": "1.3.1",
"latestVersion": "1.3.1",
"createdAt": "2023-01-04T08:50:42.000Z",
"updatedAt": "2023-01-04T08:59:20.794Z",
"links": [
{
"rel": "self",
"href": "/instances/createcloudstack/plugins/grafana-github-datasource"
},
{
"rel": "instance",
"href": "/instances/createcloudstack"
}
]
}
Regions
List regions
Use the following call to retrieve a list of regions to specify when you create a stack.
GET https://grafana.com/api/stack-regions
Responses
The following responses may be returned.
Code | Description |
---|---|
200 | Successful operation. |
401 | API token is missing or invalid. |
409 | Unexpected Parameter (InvalidArgument). |
Example response:
{
"items": [
{
"id": 1,
"status": "active",
"slug": "us",
"name": "GCP US Central",
"description": "United States",
"provider": "gcp",
"createdAt": "2021-08-20T20:00:27.000Z",
"updatedAt": "2022-12-12T12:29:37.000Z"
},
{
"id": 2,
"status": "active",
"slug": "us-azure",
"name": "Azure US Central",
"description": "United States (Azure)",
"provider": "azure",
"createdAt": "2021-08-20T20:08:03.000Z",
"updatedAt": "2022-11-29T12:04:00.000Z"
},
{
"id": 3,
"status": "active",
"slug": "eu",
"name": "GCP Belgium",
"description": "Europe",
"provider": "gcp",
"createdAt": "2021-08-20T20:28:52.000Z",
"updatedAt": "2022-12-05T18:05:33.000Z"
},
{
"id": 4,
"status": "active",
"slug": "au",
"name": "GCP Australia",
"description": "Australia",
"provider": "gcp",
"createdAt": "2021-11-16T22:03:18.000Z",
"updatedAt": "2022-09-22T09:27:47.000Z"
}
],
"orderBy": "id",
"direction": "asc",
"total": 9,
"pages": 1,
"pageSize": 1000000,
"page": 1,
"links": [
{
"rel": "self",
"href": "/stack-regions"
}
]
}
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
Was this page helpful?
Related resources from Grafana Labs
![Getting started with the Grafana LGTM Stack](/static/assets/featured/getting-started-with-grafana-lgtm-stack-amer_featured.png?w=200 200w, /static/assets/featured/getting-started-with-grafana-lgtm-stack-amer_featured.png?w=400 400w)
![Intro to Kubernetes monitoring in Grafana Cloud](/media/webinar/Screenshot-2024-02-12-at-4.09.30-PM.png?w=200 200w, /media/webinar/Screenshot-2024-02-12-at-4.09.30-PM.png?w=400 400w)
![Building advanced Grafana dashboards](/media/webinar/AMER_buildadv_notxt.png?w=200 200w, /media/webinar/AMER_buildadv_notxt.png?w=400 400w)