- Data source API
- Get all data sources
- Get a single data source by id
- Get a single data source by uid
- Get a single data source by name
- Get data source Id by name
- Create a data source
- Update an existing data source by id
- Update an existing data source
- Delete an existing data source by id
- Delete an existing data source by uid
- Delete an existing data source by name
- Data source proxy calls by id
- Data source proxy calls
- Check data source health by id
- Check data source health
- Fetch data source resources by id
- Fetch data source resources
- Query a data source
Data source API
If you are running Grafana Enterprise, for some endpoints you’ll need to have specific permissions. Refer to Role-based access control permissions for more information.
Get all data sources
GET /api/datasources
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:read | datasources:* |
Examples
Example Request:
GET /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
[
{
"id": 1,
"orgId": 1,
"uid": "H8joYFVGz"
"name": "datasource_elastic",
"type": "elasticsearch",
"typeLogoUrl": "public/app/plugins/datasource/elasticsearch/img/elasticsearch.svg",
"access": "proxy",
"url": "http://mydatasource.com",
"password": "",
"user": "",
"database": "grafana-dash",
"basicAuth": false,
"isDefault": false,
"jsonData": {
"esVersion": 5,
"logLevelField": "",
"logMessageField": "",
"maxConcurrentShardRequests": 256,
"timeField": "@timestamp"
},
"readOnly": false
}
]
Get a single data source by id
GET /api/datasources/:datasourceId
Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the API for getting a single data source by UID or to the API for getting a single data source by its name.
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:read | datasources: datasources:id: datasources:id:1 (single data source) |
Examples
Example Request:
GET /api/datasources/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
{
"id": 1,
"uid": "kLtEtcRGk",
"orgId": 1,
"name": "test_datasource",
"type": "graphite",
"typeLogoUrl": "",
"access": "proxy",
"url": "http://mydatasource.com",
"password": "",
"user": "",
"database": "",
"basicAuth": false,
"basicAuthUser": "",
"basicAuthPassword": "",
"withCredentials": false,
"isDefault": false,
"jsonData": {
"graphiteType": "default",
"graphiteVersion": "1.1"
},
"secureJsonFields": {},
"version": 1,
"readOnly": false
}
Get a single data source by uid
GET /api/datasources/uid/:uid
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:read | datasources: datasources:uid: datasources:uid:kLtEtcRGk (single data source) |
Examples
Example request:
GET /api/datasources/uid/kLtEtcRGk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
{
"id": 1,
"uid": "kLtEtcRGk",
"orgId": 1,
"name": "test_datasource",
"type": "graphite",
"typeLogoUrl": "",
"access": "proxy",
"url": "http://mydatasource.com",
"password": "",
"user": "",
"database": "",
"basicAuth": false,
"basicAuthUser": "",
"basicAuthPassword": "",
"withCredentials": false,
"isDefault": false,
"jsonData": {
"graphiteType": "default",
"graphiteVersion": "1.1"
},
"secureJsonFields": {},
"version": 1,
"readOnly": false
}
Get a single data source by name
GET /api/datasources/name/:name
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:read | datasources: datasources:name: datasources:name:test_datasource (single data source) |
Examples
Example Request:
GET /api/datasources/name/test_datasource HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
{
"id": 1,
"uid": "kLtEtcRGk",
"orgId": 1,
"name": "test_datasource",
"type": "graphite",
"typeLogoUrl": "",
"access": "proxy",
"url": "http://mydatasource.com",
"password": "",
"user": "",
"database": "",
"basicAuth": false,
"basicAuthUser": "",
"basicAuthPassword": "",
"withCredentials": false,
"isDefault": false,
"jsonData": {
"graphiteType": "default",
"graphiteVersion": "1.1"
},
"secureJsonFields": {},
"version": 1,
"readOnly": false
}
Get data source Id by name
GET /api/datasources/id/:name
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources.id:read | datasources: datasources:name: datasources:name:test_datasource (single data source) |
Examples
Example Request:
GET /api/datasources/id/test_datasource HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
{
"id":1
}
Create a data source
POST /api/datasources
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:create | n/a |
Examples
Example Graphite Request:
POST /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"name":"test_datasource",
"type":"graphite",
"url":"http://mydatasource.com",
"access":"proxy",
"basicAuth":false
}
Example Graphite Response:
HTTP/1.1 200
Content-Type: application/json
{
"datasource": {
"id": 1,
"orgId": 1,
"name": "test_datasource",
"type": "graphite",
"typeLogoUrl": "",
"access": "proxy",
"url": "http://mydatasource.com",
"password": "",
"user": "",
"database": "",
"basicAuth": false,
"basicAuthUser": "",
"basicAuthPassword": "",
"withCredentials": false,
"isDefault": false,
"jsonData": {},
"secureJsonFields": {},
"version": 1,
"readOnly": false
},
"id": 1,
"message": "Datasource added",
"name": "test_datasource"
}
Note: By defining
password
andbasicAuthPassword
undersecureJsonData
Grafana encrypts them securely as an encrypted blob in the database. The response then lists the encrypted fields undersecureJsonFields
.
Example Graphite Request with basic auth enabled:
POST /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"name": "test_datasource",
"type": "graphite",
"url": "http://mydatasource.com",
"access": "proxy",
"basicAuth": true,
"basicAuthUser": "basicuser",
"secureJsonData": {
"basicAuthPassword": "basicpassword"
}
}
Example Response with basic auth enabled:
HTTP/1.1 200
Content-Type: application/json
{
"datasource": {
"id": 1,
"orgId": 1,
"name": "test_datasource",
"type": "graphite",
"typeLogoUrl": "",
"access": "proxy",
"url": "http://mydatasource.com",
"password": "",
"user": "",
"database": "",
"basicAuth": true,
"basicAuthUser": "basicuser",
"basicAuthPassword": "",
"withCredentials": false,
"isDefault": false,
"jsonData": {},
"secureJsonFields": {
"basicAuthPassword": true
},
"version": 1,
"readOnly": false
},
"id": 102,
"message": "Datasource added",
"name": "test_datasource"
}
Example CloudWatch Request:
POST /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"name": "test_datasource",
"type": "cloudwatch",
"url": "http://monitoring.us-west-1.amazonaws.com",
"access": "proxy",
"jsonData": {
"authType": "keys",
"defaultRegion": "us-west-1"
},
"secureJsonData": {
"accessKey": "Ol4pIDpeKSA6XikgOl4p",
"secretKey": "dGVzdCBrZXkgYmxlYXNlIGRvbid0IHN0ZWFs"
}
}
Update an existing data source by id
PUT /api/datasources/:datasourceId
Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the new data source update API.
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:write | datasources: datasources:id: datasources:id:1 (single data source) |
Examples
Example Request:
PUT /api/datasources/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"id":1,
"orgId":1,
"name":"test_datasource",
"type":"graphite",
"access":"proxy",
"url":"http://mydatasource.com",
"password":"",
"user":"",
"database":"",
"basicAuth":true,
"basicAuthUser":"basicuser",
"secureJsonData": {
"basicAuthPassword": "basicpassword"
},
"isDefault":false,
"jsonData":null
}
Example Response:
HTTP/1.1 200
Content-Type: application/json
{
"datasource": {
"id": 1,
"uid": "kLtEtcRGk",
"orgId": 1,
"name": "test_datasource",
"type": "graphite",
"typeLogoUrl": "",
"access": "proxy",
"url": "http://mydatasource.com",
"password": "",
"user": "",
"database": "",
"basicAuth": true,
"basicAuthUser": "basicuser",
"basicAuthPassword": "",
"withCredentials": false,
"isDefault": false,
"jsonData": {},
"secureJsonFields": {
"basicAuthPassword": true
},
"version": 1,
"readOnly": false
},
"id": 102,
"message": "Datasource updated",
"name": "test_datasource"
}
Note: Similar to creating a data source,
password
andbasicAuthPassword
should be defined undersecureJsonData
in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed undersecureJsonFields
section in the response.
Update an existing data source
PUT /api/datasources/uid/:uid
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:write | datasources: datasources:uid: datasources:uid:kLtEtcRGk (single data source) |
Examples
Example Request:
PUT /api/datasources/uid/kLtEtcRGk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"id":1,
"uid": "updated UID",
"orgId":1,
"name":"test_datasource",
"type":"graphite",
"access":"proxy",
"url":"http://mydatasource.com",
"password":"",
"user":"",
"database":"",
"basicAuth":true,
"basicAuthUser":"basicuser",
"secureJsonData": {
"basicAuthPassword": "basicpassword"
},
"isDefault":false,
"jsonData":null
}
Example Response:
HTTP/1.1 200
Content-Type: application/json
{
"datasource": {
"id": 1,
"uid": "updated UID",
"orgId": 1,
"name": "test_datasource",
"type": "graphite",
"typeLogoUrl": "",
"access": "proxy",
"url": "http://mydatasource.com",
"password": "",
"user": "",
"database": "",
"basicAuth": true,
"basicAuthUser": "basicuser",
"basicAuthPassword": "",
"withCredentials": false,
"isDefault": false,
"jsonData": {},
"secureJsonFields": {
"basicAuthPassword": true
},
"version": 1,
"readOnly": false
},
"id": 102,
"message": "Datasource updated",
"name": "test_datasource"
}
Note: Similar to creating a data source,
password
andbasicAuthPassword
should be defined undersecureJsonData
in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed undersecureJsonFields
section in the response.## Update an existing data source by id
Delete an existing data source by id
DELETE /api/datasources/:datasourceId
Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the API for deleting an existing data source by UID or to the API for deleting an existing data source by its name
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:delete | datasources: datasources:id: datasources:id:1 (single data source) |
Examples
Example Request:
DELETE /api/datasources/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
{"message":"Data source deleted"}
Delete an existing data source by uid
DELETE /api/datasources/uid/:uid
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:delete | datasources: datasources:uid: datasources:uid:kLtEtcRGk (single data source) |
Examples
Example request:
DELETE /api/datasources/uid/kLtEtcRGk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example response:
HTTP/1.1 200
Content-Type: application/json
{
"message": "Data source deleted",
"id": 1
}
Delete an existing data source by name
DELETE /api/datasources/name/:datasourceName
Required permissions
See note in the introduction for an explanation.
Action | Scope |
---|---|
datasources:delete | datasources: datasources:name: datasources:name:test_datasource (single data source) |
Examples
Example Request:
DELETE /api/datasources/name/test_datasource HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
{
"message":"Data source deleted",
"id": 1
}
Data source proxy calls by id
Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the new data source API for proxying requests.
GET /api/datasources/proxy/:datasourceId/*
Proxies all calls to the actual data source identified by the datasourceId
.
Data source proxy calls
GET /api/datasources/proxy/uid/:uid/*
Proxies all calls to the actual data source identified by the uid
.
Check data source health by id
Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the new data source health check API.
GET /api/datasources/:datasourceId/health
Makes a call to the health endpoint of data source identified by the given dashboardId
.
Examples
Example Request:
GET api/datasources/112/health HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
{
"message": "1. Successfully queried the CloudWatch metrics API.\n2. Successfully queried the CloudWatch logs API.",
"status": "OK"
}
Check data source health
GET /api/datasources/uid/:uid/health
Makes a call to the health endpoint of data source identified by the given uid
.
Examples
Example Request:
GET api/datasources/uid/P8045C56BDA891CB2/health HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
{
"message": "1. Successfully queried the CloudWatch metrics API.\n2. Successfully queried the CloudWatch logs API.",
"status": "OK"
}
Fetch data source resources by id
Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the new data source resources API.
GET /api/datasources/:datasourceId/resources/*
Makes a call to the resources endpoint of data source identified by the given dashboardId
.
Examples
Example Request:
GET api/datasources/112/resources/dimension-keys?region=us-east-2&namespace=AWS%2FEC2&dimensionFilters=%7B%7D&metricName=CPUUtilization HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
[
{
"text": "AutoScalingGroupName",
"value": "AutoScalingGroupName",
"label": "AutoScalingGroupName"
},
{
"text": "ImageId",
"value": "ImageId",
"label": "ImageId"
},
{
"text": "InstanceId",
"value": "InstanceId",
"label": "InstanceId"
},
{
"text": "InstanceType",
"value": "InstanceType",
"label": "InstanceType"
}
]
Fetch data source resources
GET /api/datasources/uid/:uid/resources/*
Makes a call to the resources endpoint of data source identified by the given uid
.
Examples
Example Request:
GET api/datasources/uid/P8045C56BDA891CB2/resources/dimension-keys?region=us-east-2&namespace=AWS%2FEC2&dimensionFilters=%7B%7D&metricName=CPUUtilization HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Example Response:
HTTP/1.1 200
Content-Type: application/json
[
{
"text": "AutoScalingGroupName",
"value": "AutoScalingGroupName",
"label": "AutoScalingGroupName"
},
{
"text": "ImageId",
"value": "ImageId",
"label": "ImageId"
},
{
"text": "InstanceId",
"value": "InstanceId",
"label": "InstanceId"
},
{
"text": "InstanceType",
"value": "InstanceType",
"label": "InstanceType"
}
]
Query a data source
Queries a data source having a backend implementation.
POST /api/ds/query
Note: Grafana’s built-in data sources usually have a backend implementation.
Example request for the Test data source:
POST /api/ds/query HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"queries":[
{
"refId":"A",
"scenarioId":"csv_metric_values",
"datasource":{
"uid":"PD8C576611E62080A"
},
"format": "table"
"maxDataPoints":1848,
"intervalMs":200,
"stringInput":"1,20,90,30,5,0",
}
],
"from":"now-5m",
"to":"now"
}
JSON Body schema:
- from/to – Specifies the time range for the queries. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example,
now-5m
. - queries – Specifies one or more queries. Must contain at least 1.
- queries.datasource.uid – Specifies the UID of data source to be queried. Each query in the request must have a unique
datasource
. - queries.refId – Specifies an identifier of the query. Defaults to “A”.
- queries.format – Specifies the format the data should be returned in. Valid options are
time_series
ortable
depending on the data source. - queries.maxDataPoints - Species the maximum amount of data points that a dashboard panel can render. Defaults to 100.
- queries.intervalMs - Specifies the time series time interval in milliseconds. Defaults to 1000.
In addition, specific properties of each data source should be added in a request (for example queries.stringInput as shown in the request above). To better understand how to form a query for a certain data source, use the Developer Tools in your browser of choice and inspect the HTTP requests being made to /api/ds/query
.
Example Test data source time series query response:
{
"results": {
"A": {
"frames": [
{
"schema": {
"refId": "A",
"fields": [
{
"name": "time",
"type": "time",
"typeInfo": {
"frame": "time.Time"
}
},
{
"name": "A-series",
"type": "number",
"typeInfo": {
"frame": "int64",
"nullable": true
}
}
]
},
"data": {
"values": [
[1644488152084, 1644488212084, 1644488272084, 1644488332084, 1644488392084, 1644488452084],
[1, 20, 90, 30, 5, 0]
]
}
}
]
}
}
}
Status codes
Code | Description |
---|---|
200 | All data source queries returned a successful response. |
400 | Bad request due to invalid JSON, missing content type, missing or invalid fields, etc. Or one or more data source queries were unsuccessful. Refer to the body for more details. |
403 | Access denied. |
404 | Either the data source or plugin required to fulfil the request could not be found. |
500 | Unexpected error. Refer to the body and/or server logs for more details. |