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.

ActionScope
datasources:readdatasources:*

Examples

Example Request:

  1. GET /api/datasources HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. [
  4. {
  5. "id": 1,
  6. "orgId": 1,
  7. "uid": "H8joYFVGz"
  8. "name": "datasource_elastic",
  9. "type": "elasticsearch",
  10. "typeLogoUrl": "public/app/plugins/datasource/elasticsearch/img/elasticsearch.svg",
  11. "access": "proxy",
  12. "url": "http://mydatasource.com",
  13. "password": "",
  14. "user": "",
  15. "database": "grafana-dash",
  16. "basicAuth": false,
  17. "isDefault": false,
  18. "jsonData": {
  19. "esVersion": 5,
  20. "logLevelField": "",
  21. "logMessageField": "",
  22. "maxConcurrentShardRequests": 256,
  23. "timeField": "@timestamp"
  24. },
  25. "readOnly": false
  26. }
  27. ]

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.

ActionScope
datasources:readdatasources:
datasources:id:

datasources:id:1 (single data source)

Examples

Example Request:

  1. GET /api/datasources/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "id": 1,
  5. "uid": "kLtEtcRGk",
  6. "orgId": 1,
  7. "name": "test_datasource",
  8. "type": "graphite",
  9. "typeLogoUrl": "",
  10. "access": "proxy",
  11. "url": "http://mydatasource.com",
  12. "password": "",
  13. "user": "",
  14. "database": "",
  15. "basicAuth": false,
  16. "basicAuthUser": "",
  17. "basicAuthPassword": "",
  18. "withCredentials": false,
  19. "isDefault": false,
  20. "jsonData": {
  21. "graphiteType": "default",
  22. "graphiteVersion": "1.1"
  23. },
  24. "secureJsonFields": {},
  25. "version": 1,
  26. "readOnly": false
  27. }

Get a single data source by uid

GET /api/datasources/uid/:uid

Required permissions

See note in the introduction for an explanation.

ActionScope
datasources:readdatasources:
datasources:uid:

datasources:uid:kLtEtcRGk (single data source)

Examples

Example request:

  1. GET /api/datasources/uid/kLtEtcRGk HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "id": 1,
  5. "uid": "kLtEtcRGk",
  6. "orgId": 1,
  7. "name": "test_datasource",
  8. "type": "graphite",
  9. "typeLogoUrl": "",
  10. "access": "proxy",
  11. "url": "http://mydatasource.com",
  12. "password": "",
  13. "user": "",
  14. "database": "",
  15. "basicAuth": false,
  16. "basicAuthUser": "",
  17. "basicAuthPassword": "",
  18. "withCredentials": false,
  19. "isDefault": false,
  20. "jsonData": {
  21. "graphiteType": "default",
  22. "graphiteVersion": "1.1"
  23. },
  24. "secureJsonFields": {},
  25. "version": 1,
  26. "readOnly": false
  27. }

Get a single data source by name

GET /api/datasources/name/:name

Required permissions

See note in the introduction for an explanation.

ActionScope
datasources:readdatasources:
datasources:name:

datasources:name:test_datasource (single data source)

Examples

Example Request:

  1. GET /api/datasources/name/test_datasource HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "id": 1,
  5. "uid": "kLtEtcRGk",
  6. "orgId": 1,
  7. "name": "test_datasource",
  8. "type": "graphite",
  9. "typeLogoUrl": "",
  10. "access": "proxy",
  11. "url": "http://mydatasource.com",
  12. "password": "",
  13. "user": "",
  14. "database": "",
  15. "basicAuth": false,
  16. "basicAuthUser": "",
  17. "basicAuthPassword": "",
  18. "withCredentials": false,
  19. "isDefault": false,
  20. "jsonData": {
  21. "graphiteType": "default",
  22. "graphiteVersion": "1.1"
  23. },
  24. "secureJsonFields": {},
  25. "version": 1,
  26. "readOnly": false
  27. }

Get data source Id by name

GET /api/datasources/id/:name

Required permissions

See note in the introduction for an explanation.

ActionScope
datasources.id:readdatasources:
datasources:name:

datasources:name:test_datasource (single data source)

Examples

Example Request:

  1. GET /api/datasources/id/test_datasource HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "id":1
  5. }

Create a data source

POST /api/datasources

Required permissions

See note in the introduction for an explanation.

ActionScope
datasources:createn/a

Examples

Example Graphite Request:

  1. POST /api/datasources HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  5. {
  6. "name":"test_datasource",
  7. "type":"graphite",
  8. "url":"http://mydatasource.com",
  9. "access":"proxy",
  10. "basicAuth":false
  11. }

Example Graphite Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "datasource": {
  5. "id": 1,
  6. "orgId": 1,
  7. "name": "test_datasource",
  8. "type": "graphite",
  9. "typeLogoUrl": "",
  10. "access": "proxy",
  11. "url": "http://mydatasource.com",
  12. "password": "",
  13. "user": "",
  14. "database": "",
  15. "basicAuth": false,
  16. "basicAuthUser": "",
  17. "basicAuthPassword": "",
  18. "withCredentials": false,
  19. "isDefault": false,
  20. "jsonData": {},
  21. "secureJsonFields": {},
  22. "version": 1,
  23. "readOnly": false
  24. },
  25. "id": 1,
  26. "message": "Datasource added",
  27. "name": "test_datasource"
  28. }

Note: By defining password and basicAuthPassword under secureJsonData Grafana encrypts them securely as an encrypted blob in the database. The response then lists the encrypted fields under secureJsonFields.

Example Graphite Request with basic auth enabled:

  1. POST /api/datasources HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  5. {
  6. "name": "test_datasource",
  7. "type": "graphite",
  8. "url": "http://mydatasource.com",
  9. "access": "proxy",
  10. "basicAuth": true,
  11. "basicAuthUser": "basicuser",
  12. "secureJsonData": {
  13. "basicAuthPassword": "basicpassword"
  14. }
  15. }

Example Response with basic auth enabled:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "datasource": {
  5. "id": 1,
  6. "orgId": 1,
  7. "name": "test_datasource",
  8. "type": "graphite",
  9. "typeLogoUrl": "",
  10. "access": "proxy",
  11. "url": "http://mydatasource.com",
  12. "password": "",
  13. "user": "",
  14. "database": "",
  15. "basicAuth": true,
  16. "basicAuthUser": "basicuser",
  17. "basicAuthPassword": "",
  18. "withCredentials": false,
  19. "isDefault": false,
  20. "jsonData": {},
  21. "secureJsonFields": {
  22. "basicAuthPassword": true
  23. },
  24. "version": 1,
  25. "readOnly": false
  26. },
  27. "id": 102,
  28. "message": "Datasource added",
  29. "name": "test_datasource"
  30. }

Example CloudWatch Request:

  1. POST /api/datasources HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  5. {
  6. "name": "test_datasource",
  7. "type": "cloudwatch",
  8. "url": "http://monitoring.us-west-1.amazonaws.com",
  9. "access": "proxy",
  10. "jsonData": {
  11. "authType": "keys",
  12. "defaultRegion": "us-west-1"
  13. },
  14. "secureJsonData": {
  15. "accessKey": "Ol4pIDpeKSA6XikgOl4p",
  16. "secretKey": "dGVzdCBrZXkgYmxlYXNlIGRvbid0IHN0ZWFs"
  17. }
  18. }

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.

ActionScope
datasources:writedatasources:
datasources:id:

datasources:id:1 (single data source)

Examples

Example Request:

  1. PUT /api/datasources/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  5. {
  6. "id":1,
  7. "orgId":1,
  8. "name":"test_datasource",
  9. "type":"graphite",
  10. "access":"proxy",
  11. "url":"http://mydatasource.com",
  12. "password":"",
  13. "user":"",
  14. "database":"",
  15. "basicAuth":true,
  16. "basicAuthUser":"basicuser",
  17. "secureJsonData": {
  18. "basicAuthPassword": "basicpassword"
  19. },
  20. "isDefault":false,
  21. "jsonData":null
  22. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "datasource": {
  5. "id": 1,
  6. "uid": "kLtEtcRGk",
  7. "orgId": 1,
  8. "name": "test_datasource",
  9. "type": "graphite",
  10. "typeLogoUrl": "",
  11. "access": "proxy",
  12. "url": "http://mydatasource.com",
  13. "password": "",
  14. "user": "",
  15. "database": "",
  16. "basicAuth": true,
  17. "basicAuthUser": "basicuser",
  18. "basicAuthPassword": "",
  19. "withCredentials": false,
  20. "isDefault": false,
  21. "jsonData": {},
  22. "secureJsonFields": {
  23. "basicAuthPassword": true
  24. },
  25. "version": 1,
  26. "readOnly": false
  27. },
  28. "id": 102,
  29. "message": "Datasource updated",
  30. "name": "test_datasource"
  31. }

Note: Similar to creating a data source, password and basicAuthPassword should be defined under secureJsonData in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed under secureJsonFields section in the response.

Update an existing data source

PUT /api/datasources/uid/:uid

Required permissions

See note in the introduction for an explanation.

ActionScope
datasources:writedatasources:
datasources:uid:

datasources:uid:kLtEtcRGk (single data source)

Examples

Example Request:

  1. PUT /api/datasources/uid/kLtEtcRGk HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  5. {
  6. "id":1,
  7. "uid": "updated UID",
  8. "orgId":1,
  9. "name":"test_datasource",
  10. "type":"graphite",
  11. "access":"proxy",
  12. "url":"http://mydatasource.com",
  13. "password":"",
  14. "user":"",
  15. "database":"",
  16. "basicAuth":true,
  17. "basicAuthUser":"basicuser",
  18. "secureJsonData": {
  19. "basicAuthPassword": "basicpassword"
  20. },
  21. "isDefault":false,
  22. "jsonData":null
  23. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "datasource": {
  5. "id": 1,
  6. "uid": "updated UID",
  7. "orgId": 1,
  8. "name": "test_datasource",
  9. "type": "graphite",
  10. "typeLogoUrl": "",
  11. "access": "proxy",
  12. "url": "http://mydatasource.com",
  13. "password": "",
  14. "user": "",
  15. "database": "",
  16. "basicAuth": true,
  17. "basicAuthUser": "basicuser",
  18. "basicAuthPassword": "",
  19. "withCredentials": false,
  20. "isDefault": false,
  21. "jsonData": {},
  22. "secureJsonFields": {
  23. "basicAuthPassword": true
  24. },
  25. "version": 1,
  26. "readOnly": false
  27. },
  28. "id": 102,
  29. "message": "Datasource updated",
  30. "name": "test_datasource"
  31. }

Note: Similar to creating a data source, password and basicAuthPassword should be defined under secureJsonData in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed under secureJsonFields 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.

ActionScope
datasources:deletedatasources:
datasources:id:

datasources:id:1 (single data source)

Examples

Example Request:

  1. DELETE /api/datasources/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"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.

ActionScope
datasources:deletedatasources:
datasources:uid:

datasources:uid:kLtEtcRGk (single data source)

Examples

Example request:

  1. DELETE /api/datasources/uid/kLtEtcRGk HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "message": "Data source deleted",
  5. "id": 1
  6. }

Delete an existing data source by name

DELETE /api/datasources/name/:datasourceName

Required permissions

See note in the introduction for an explanation.

ActionScope
datasources:deletedatasources:
datasources:name:

datasources:name:test_datasource (single data source)

Examples

Example Request:

  1. DELETE /api/datasources/name/test_datasource HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "message":"Data source deleted",
  5. "id": 1
  6. }

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:

  1. GET api/datasources/112/health HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "message": "1. Successfully queried the CloudWatch metrics API.\n2. Successfully queried the CloudWatch logs API.",
  5. "status": "OK"
  6. }

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:

  1. GET api/datasources/uid/P8045C56BDA891CB2/health HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "message": "1. Successfully queried the CloudWatch metrics API.\n2. Successfully queried the CloudWatch logs API.",
  5. "status": "OK"
  6. }

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:

  1. GET api/datasources/112/resources/dimension-keys?region=us-east-2&namespace=AWS%2FEC2&dimensionFilters=%7B%7D&metricName=CPUUtilization HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. [
  4. {
  5. "text": "AutoScalingGroupName",
  6. "value": "AutoScalingGroupName",
  7. "label": "AutoScalingGroupName"
  8. },
  9. {
  10. "text": "ImageId",
  11. "value": "ImageId",
  12. "label": "ImageId"
  13. },
  14. {
  15. "text": "InstanceId",
  16. "value": "InstanceId",
  17. "label": "InstanceId"
  18. },
  19. {
  20. "text": "InstanceType",
  21. "value": "InstanceType",
  22. "label": "InstanceType"
  23. }
  24. ]

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:

  1. GET api/datasources/uid/P8045C56BDA891CB2/resources/dimension-keys?region=us-east-2&namespace=AWS%2FEC2&dimensionFilters=%7B%7D&metricName=CPUUtilization HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. [
  4. {
  5. "text": "AutoScalingGroupName",
  6. "value": "AutoScalingGroupName",
  7. "label": "AutoScalingGroupName"
  8. },
  9. {
  10. "text": "ImageId",
  11. "value": "ImageId",
  12. "label": "ImageId"
  13. },
  14. {
  15. "text": "InstanceId",
  16. "value": "InstanceId",
  17. "label": "InstanceId"
  18. },
  19. {
  20. "text": "InstanceType",
  21. "value": "InstanceType",
  22. "label": "InstanceType"
  23. }
  24. ]

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:

  1. POST /api/ds/query HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "queries":[
  6. {
  7. "refId":"A",
  8. "scenarioId":"csv_metric_values",
  9. "datasource":{
  10. "uid":"PD8C576611E62080A"
  11. },
  12. "format": "table"
  13. "maxDataPoints":1848,
  14. "intervalMs":200,
  15. "stringInput":"1,20,90,30,5,0",
  16. }
  17. ],
  18. "from":"now-5m",
  19. "to":"now"
  20. }

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 or table 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:

  1. {
  2. "results": {
  3. "A": {
  4. "frames": [
  5. {
  6. "schema": {
  7. "refId": "A",
  8. "fields": [
  9. {
  10. "name": "time",
  11. "type": "time",
  12. "typeInfo": {
  13. "frame": "time.Time"
  14. }
  15. },
  16. {
  17. "name": "A-series",
  18. "type": "number",
  19. "typeInfo": {
  20. "frame": "int64",
  21. "nullable": true
  22. }
  23. }
  24. ]
  25. },
  26. "data": {
  27. "values": [
  28. [1644488152084, 1644488212084, 1644488272084, 1644488332084, 1644488392084, 1644488452084],
  29. [1, 20, 90, 30, 5, 0]
  30. ]
  31. }
  32. }
  33. ]
  34. }
  35. }
  36. }

Status codes

CodeDescription
200All data source queries returned a successful response.
400Bad 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.
403Access denied.
404Either the data source or plugin required to fulfil the request could not be found.
500Unexpected error. Refer to the body and/or server logs for more details.