Data source API

If you are running Grafana Enterprise and have Fine-grained access control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required.

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

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

PUT /api/datasources/:datasourceId

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. "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 updated",
  29. "name": "test_datasource"
  30. }

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.

Delete an existing data source by id

DELETE /api/datasources/:datasourceId

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. {"message":"Data source deleted"}

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

GET /api/datasources/proxy/:datasourceId/*

Proxies all calls to the actual data source.

Query a data source by ID

Queries a data source having backend implementation.

POST /api/tsdb/query

Note: Most of Grafana’s builtin data sources have backend implementation.

Example Request:

  1. POST /api/tsdb/query HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "from": "1420066800000",
  6. "to": "1575845999999",
  7. "queries": [
  8. {
  9. "refId": "A",
  10. "intervalMs": 86400000,
  11. "maxDataPoints": 1092,
  12. "datasourceId": 86,
  13. "rawSql": "SELECT 1 as valueOne, 2 as valueTwo",
  14. "format": "table"
  15. }
  16. ]
  17. }

Note: The from, to, and queries properties are required.

JSON Body schema:

  • from/to – Should be either absolute in epoch timestamps in milliseconds or relative using Grafana time units. For example, now-1h.
  • queries.refId – Specifies an identifier of the query. Is optional and default to “A”.
  • queries.datasourceId – Specifies the data source to be queried. Each query in the request must have an unique datasourceId.
  • queries.maxDataPoints - Species maximum amount of data points that dashboard panel can render. Is optional and default to 100.
  • queries.intervalMs - Specifies the time interval in milliseconds of time series. Is optional and defaults to 1000.

In addition, each data source has its own specific properties that should be added in a request.

Example request for the MySQL data source:

  1. POST /api/tsdb/query HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "from": "1420066800000",
  6. "to": "1575845999999",
  7. "queries": [
  8. {
  9. "refId": "A",
  10. "intervalMs": 86400000,
  11. "maxDataPoints": 1092,
  12. "datasourceId": 86,
  13. "rawSql": "SELECT\n time,\n sum(opened) AS \"Opened\",\n sum(closed) AS \"Closed\"\nFROM\n issues_activity\nWHERE\n $__unixEpochFilter(time) AND\n period = 'm' AND\n repo IN('grafana/grafana') AND\n opened_by IN('Contributor','Grafana Labs')\nGROUP BY 1\nORDER BY 1\n",
  14. "format": "time_series"
  15. }
  16. ]
  17. }

Example MySQL time series query response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "results": {
  5. "A": {
  6. "refId": "A",
  7. "meta": {
  8. "rowCount": 0,
  9. "sql": "SELECT\n time,\n sum(opened) AS \"Opened\",\n sum(closed) AS \"Closed\"\nFROM\n issues_activity\nWHERE\n time >= 1420066800 AND time <= 1575845999 AND\n period = 'm' AND\n repo IN('grafana/grafana') AND\n opened_by IN('Contributor','Grafana Labs')\nGROUP BY 1\nORDER BY 1\n"
  10. },
  11. "series": [
  12. {
  13. "name": "Opened",
  14. "points": [
  15. [
  16. 109,
  17. 1420070400000
  18. ],
  19. [
  20. 122,
  21. 1422748800000
  22. ]
  23. ]
  24. },
  25. {
  26. "name": "Closed",
  27. "points": [
  28. [
  29. 89,
  30. 1420070400000
  31. ]
  32. ]
  33. }
  34. ]
  35. }
  36. }
  37. }