Project: Grafana (Observability and Analysis / Observability)
File: data_source.md

aliases: ../../httpapi/datasource/ ../../http_api/datasource/ canonical: /docs/grafana/latest/developers/httpapi/datasource/ description: Grafana Data source HTTP API keywords: grafana http documentation api data source labels: products: enterprise oss title: Data source HTTP API If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to for more information. `GET /api/datasources` {{% admonition type="warning" %}} This API currently doesn't handle pagination. The default maximum number of data sources returned is 5000. You can change this value in the default.ini file. {{% /admonition %}} Required permissions See note in the for an explanation. | Action | Scope | | - | -- | | datasources:read | datasources:\* | Example Request: ```http GET /api/datasources HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example Response: ```http 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": { "logLevelField": "", "logMessageField": "", "maxConcurrentShardRequests": 256, "timeField": "@timestamp" }, "readOnly": false } ] ``` `GET /api/datasources/:datasourceId` {{% admonition type="warning" %}} This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the or to the . {{% /admonition %}} Required permissions See note in the for an explanation. | Action | Scope | | - | - | | datasources:read | datasources:\<br>datasources:id:\<br>datasources:id:1 (single data source) | Example Request: ```http GET /api/datasources/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example Response: ```http 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 /api/datasources/uid/:uid` Required permissions See note in the for an explanation. | Action | Scope | | - | -- | | datasources:read | datasources:\<br>datasources:uid:\<br>datasources:uid:kLtEtcRGk (single data source) | Example request: ```http GET /api/datasources/uid/kLtEtcRGk HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example Response: ```http 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 /api/datasources/name/:name` Required permissions See note in the for an explanation. | Action | Scope | | - | - | | datasources:read | datasources:\<br>datasources:name:\<br>datasources:name:test_datasource (single data source) | Example Request: ```http GET /api/datasources/name/test_datasource HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example Response: ```http 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 /api/datasources/id/:name` Required permissions See note in the for an explanation. | Action | Scope | | - | - | | datasources.id:read | datasources:\<br>datasources:name:\<br>datasources:name:test_datasource (single data source) | Example Request: ```http GET /api/datasources/id/test_datasource HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example Response: ```http

200 Content-Type: application/json { "id":1 } ``` `POST /api/datasources` Required permissions See note in the for an explanation. | Action | Scope | | | -- | | datasources:create | n/a | Example Graphite Request: ```http 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 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" } ``` {{% admonition type="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`. {{% /admonition %}} Example Graphite Request with basic auth enabled: ```http 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 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: ```http 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" } } ``` `PUT /api/datasources/:datasourceId` {{% admonition type="warning" %}} This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the . {{% /admonition %}} Required permissions See note in the for an explanation. | Action | Scope | | -- | - | | datasources:write | datasources:\<br>datasources:id:\<br>datasources:id:1 (single data source) | Example Request: ```http 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 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" } ``` {{% admonition type="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. {{% /admonition %}} `PUT /api/datasources/uid/:uid` Required permissions See note in the for an explanation. | Action | Scope | | -- | -- | | datasources:write | datasources:\<br>datasources:uid:\<br>datasources:uid:kLtEtcRGk (single data source) | Example Request: ```http 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

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" } ``` {{% admonition type="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 {{% /admonition %}} `DELETE /api/datasources/:datasourceId` {{% admonition type="warning" %}} This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the or to the {{% /admonition %}} Required permissions See note in the for an explanation. | Action | Scope | | | - | | datasources:delete | datasources:\<br>datasources:id:\<br>datasources:id:1 (single data source) | Example Request: ```http DELETE /api/datasources/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example Response: ```http HTTP/1.1 200 Content-Type: application/json {"message":"Data source deleted"} ``` `DELETE /api/datasources/uid/:uid` Required permissions See note in the for an explanation. | Action | Scope | | | -- | | datasources:delete | datasources:\<br>datasources:uid:\<br>datasources:uid:kLtEtcRGk (single data source) | Example request: ```http DELETE /api/datasources/uid/kLtEtcRGk HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example response: ```http HTTP/1.1 200 Content-Type: application/json { "message": "Data source deleted", "id": 1 } ``` `DELETE /api/datasources/name/:datasourceName` Required permissions See note in the for an explanation. | Action | Scope | | | - | | datasources:delete | datasources:\<br>datasources:name:\<br>datasources:name:test_datasource (single data source) | Example Request: ```http DELETE /api/datasources/name/test_datasource HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example Response: ```http HTTP/1.1 200 Content-Type: application/json { "message":"Data source deleted", "id": 1 } ``` {{% admonition type="warning" %}} This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the . {{% /admonition %}} `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`. Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the . `GET /api/datasources/:datasourceId/health` Makes a call to the health endpoint of data source identified by the given `datasourceId`. This is not mandatory - every plugin author has to <a href="https://grafana.com/tutorials/build-a-data-source-backend-plugin/#add-support-for-health-checks" target="_blank">implement support for health checks</a> in their plugin themselves. Example Request: ```http GET api/datasources/112/health HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example Response: ```http 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" } ``` `GET /api/datasources/uid/:uid/health` Makes a call to the health endpoint of data source identified by the given `uid`. This is not mandatory - every plugin author has to <a href="https://grafana.com/tutorials/build-a-data-source-backend-plugin/#add-support-for-health-checks" target="_blank">implement support for health checks</a> in their plugin themselves. Example Request: ```http GET api/datasources/uid/P8045C56BDA891CB2/health HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Example Response: ```http 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" } ``` {{% admonition type="warning" %}} This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the

{{% /admonition %}} `GET /api/datasources/:datasourceId/resources/*` Makes a call to the resources endpoint of data source identified by the given `dashboardId`. Example Request: ```http 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 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" } ] ``` `GET /api/datasources/uid/:uid/resources/*` Makes a call to the resources endpoint of data source identified by the given `uid`. Example Request: ```http 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 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" } ] ``` Queries a data source having a backend implementation. `POST /api/ds/query` {{% admonition type="note" %}} Grafana's built-in data sources usually have a backend implementation. {{% /admonition %}} Example request for the Test data source: ```http POST /api/ds/query HTTP/1.1 Accept: application/json Content-Type: application/json { "queries":[ { "refId":"A", "scenarioId":"csvmetricvalues", "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` 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: ```json { "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] ] } } ] } } } ``` | 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. |