Data source API

    Required permissions

    See note in the for an explanation.

    Example Request:

    Example Response:

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

    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 .

    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
    4. {
    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": false,
    17.   "basicAuthUser": "",
    18.   "basicAuthPassword": "",
    19.   "withCredentials": false,
    20.   "isDefault": false,
    21.   "jsonData": {
    22.     "graphiteType": "default",
    23.     "graphiteVersion": "1.1"
    24.   },
    25.   "secureJsonFields": {},
    26.   "version": 1,
    27.   "readOnly": false
    28. }

    Get a single data source by uid

    GET /api/datasources/uid/:uid

    Required permissions

    See note in the 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
    4. {
    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": false,
    17.   "basicAuthUser": "",
    18.   "basicAuthPassword": "",
    19.   "withCredentials": false,
    20.   "isDefault": false,
    21.   "jsonData": {
    22.     "graphiteType": "default",
    23.     "graphiteVersion": "1.1"
    24.   },
    25.   "secureJsonFields": {},
    26.   "version": 1,
    27.   "readOnly": false
    28. }

    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
    4. {
    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": false,
    17.   "basicAuthUser": "",
    18.   "basicAuthPassword": "",
    19.   "withCredentials": false,
    20.   "isDefault": false,
    21.   "jsonData": {
    22.     "graphiteType": "default",
    23.     "graphiteVersion": "1.1"
    24.   },
    25.   "secureJsonFields": {},
    26.   "version": 1,
    27.   "readOnly": false
    28. }

    Get data source Id by name

    GET /api/datasources/id/:name

    Required permissions

    See note in the for an explanation.

    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
    4. {
    5.   "id":1

    Create a data source

    POST /api/datasources

    Required permissions

    See note in the introduction for an explanation.

    ActionScope
    datasources:createn/a

    Example Graphite Request:

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

    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
    6. {
    7.   "name": "test_datasource",
    8.   "type": "graphite",
    9.   "url": "http://mydatasource.com",
    10.   "access": "proxy",
    11.   "basicAuth": true,
    13.   "secureJsonData": {
    14.     "basicAuthPassword": "basicpassword"
    15.   }
    16. }

    Example Response with basic auth enabled:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.   "datasource": {
    6.     "id": 1,
    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 added",
    30.   "name": "test_datasource"
    31. }

    Example CloudWatch Request:

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

    PUT /api/datasources/:datasourceId

    Required permissions

    See note in the 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
    6. {
    7.   "id":1,
    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
    4. {
    5.   "datasource": {
    6.     "id": 1,
    7.     "uid": "kLtEtcRGk",
    8.     "orgId": 1,
    9.     "name": "test_datasource",
    10.     "type": "graphite",
    11.     "typeLogoUrl": "",
    12.     "access": "proxy",
    13.     "url": "http://mydatasource.com",
    14.     "password": "",
    15.     "user": "",
    16.     "database": "",
    17.     "basicAuth": true,
    18.     "basicAuthUser": "basicuser",
    19.     "basicAuthPassword": "",
    20.     "withCredentials": false,
    21.     "isDefault": false,
    22.     "jsonData": {},
    23.     "secureJsonFields": {
    24.       "basicAuthPassword": true
    25.     },
    26.     "version": 1,
    27.     "readOnly": false
    28.   },
    29.   "id": 102,
    30.   "message": "Datasource updated",
    31.   "name": "test_datasource"
    32. }

    Note: Similar to , 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 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
    6. {
    7.   "id":1,
    8.   "uid": "updated UID",
    9.   "orgId":1,
    10.   "name":"test_datasource",
    11.   "type":"graphite",
    12.   "access":"proxy",
    13.   "url":"http://mydatasource.com",
    14.   "password":"",
    15.   "user":"",
    16.   "database":"",
    17.   "basicAuth":true,
    18.   "basicAuthUser":"basicuser",
    19.   "secureJsonData": {
    20.     "basicAuthPassword": "basicpassword"
    21.   },
    22.   "isDefault":false,
    23.   "jsonData":null
    24. }

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.   "datasource": {
    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.     "basicAuthPassword": "",
    19.     "withCredentials": false,
    20.     "isDefault": false,
    21.     "jsonData": {},
    22.     "secureJsonFields": {
    23.       "basicAuthPassword": true
    24.     },
    25.     "version": 1,
    26.     "readOnly": false
    28.   "id": 102,
    29.   "message": "Datasource updated",
    30.   "name": "test_datasource"
    31. }

    Note: Similar to , 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

    Required permissions

    See note in the for an explanation.

    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
    4. {"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:

    Delete an existing data source by name

    DELETE /api/datasources/name/:datasourceName

    Required permissions

    ActionScope
    datasources:deletedatasources:
    datasources:name:
    datasources:name:test_datasource (single data source)

    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
    4. {
    5.   "message":"Data source deleted",
    6.   "id": 1
    7. }

    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 .

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

    Proxies all calls to the actual data source identified by the datasourceId.

    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
    4. {
    5.   "message": "1. Successfully queried the CloudWatch metrics API.\n2. Successfully queried the CloudWatch logs API.",
    6.   "status": "OK"
    7. }

    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
    4. {
    5.   "message": "1. Successfully queried the CloudWatch metrics API.\n2. Successfully queried the CloudWatch logs API.",
    6.   "status": "OK"
    7. }

    Fetch data source resources by id

    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
    4. [
    5.     {
    6.         "text": "AutoScalingGroupName",
    7.         "value": "AutoScalingGroupName",
    8.         "label": "AutoScalingGroupName"
    9.     },
    10.     {
    11.         "text": "ImageId",
    12.         "value": "ImageId",
    13.         "label": "ImageId"
    14.     },
    15.     {
    16.         "text": "InstanceId",
    17.         "value": "InstanceId",
    18.         "label": "InstanceId"
    19.     },
    20.     {
    21.         "text": "InstanceType",
    22.         "value": "InstanceType",
    23.         "label": "InstanceType"
    24.     }
    25. ]

    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
    4. [
    5.     {
    6.         "text": "AutoScalingGroupName",
    7.         "value": "AutoScalingGroupName",
    8.         "label": "AutoScalingGroupName"
    9.     },
    10.     {
    11.         "text": "ImageId",
    12.         "value": "ImageId",
    13.         "label": "ImageId"
    14.     },
    15.     {
    16.         "text": "InstanceId",
    17.         "value": "InstanceId",
    18.         "label": "InstanceId"
    19.     },
    20.     {
    21.         "text": "InstanceType",
    22.         "value": "InstanceType",
    23.         "label": "InstanceType"
    24.     }
    25. ]

    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:

    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.

    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.     }
    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.