mirror of
https://github.com/grafana/grafana.git
synced 2025-07-28 06:42:04 +08:00
c1c48dd610
* Use relative aliases for all non-current Grafana aliases
Prevents non-latest documentation "stealing" the page away from latest
and through permanent redirects for latest pages that no longer exist.
The redirected pages are indexed by search engines but our robots.txt
forbids them crawling the non-latest page.
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Remove aliases from shared pages
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Rewrite all current latest aliases to be next
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Fix typo in latest alias
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Remove all current page aliases
find docs/sources -type f -name '*.md' -exec sed -z -i 's#\n *- /docs/grafana/next/[^\n]*\n#\n#' {} \;
find docs/sources -type f -name '*.md' -exec sed -Ez -i 's#\n((aliases:\n *-)|aliases:\n)#\n\2#' {} \;
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Prettier
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
962 lines
25 KiB
Markdown
962 lines
25 KiB
Markdown
---
|
||
aliases:
|
||
- ../../http_api/data_source/
|
||
- ../../http_api/datasource/
|
||
description: Grafana Data source HTTP API
|
||
keywords:
|
||
- grafana
|
||
- http
|
||
- documentation
|
||
- api
|
||
- data source
|
||
title: Data source HTTP API
|
||
---
|
||
|
||
# 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]({{< relref "../../administration/roles-and-permissions/access-control/custom-role-actions-scopes/" >}}) for more information.
|
||
|
||
## Get all data sources
|
||
|
||
`GET /api/datasources`
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | -------------- |
|
||
| datasources:read | datasources:\* |
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## 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](#get-a-single-data-source-by-uid) or to the [API for getting a single data source by its name](#get-a-single-data-source-by-name).
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | ---------------------------------------------------------------------------- |
|
||
| datasources:read | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## Get a single data source by uid
|
||
|
||
`GET /api/datasources/uid/:uid`
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | -------------------------------------------------------------------------------------- |
|
||
| datasources:read | datasources:\*<br>datasources:uid:\*<br>datasources:uid:kLtEtcRGk (single data source) |
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## Get a single data source by name
|
||
|
||
`GET /api/datasources/name/:name`
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | ---------------------------------------------------------------------------------------------- |
|
||
| datasources:read | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## Get data source Id by name
|
||
|
||
`GET /api/datasources/id/:name`
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------- | ---------------------------------------------------------------------------------------------- |
|
||
| datasources.id:read | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||
|
||
### Examples
|
||
|
||
**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
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
## Create a data source
|
||
|
||
`POST /api/datasources`
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------ | ----- |
|
||
| datasources:create | n/a |
|
||
|
||
### Examples
|
||
|
||
**Example Graphite Request**:
|
||
|
||
```http
|
||
POST /api/datasources HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
|
||
```
|
||
|
||
**Example Graphite Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
> **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**:
|
||
|
||
```http
|
||
POST /api/datasources HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
|
||
```
|
||
|
||
**Example Response with basic auth enabled**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
**Example CloudWatch Request**:
|
||
|
||
```http
|
||
POST /api/datasources HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
|
||
```
|
||
|
||
## 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](#update-an-existing-data-source).
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ----------------- | ---------------------------------------------------------------------------- |
|
||
| datasources:write | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
PUT /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
|
||
|
||
```
|
||
|
||
> **Note:** Similar to [creating a data source](#create-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]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ----------------- | -------------------------------------------------------------------------------------- |
|
||
| datasources:write | datasources:\*<br>datasources:uid:\*<br>datasources:uid:kLtEtcRGk (single data source) |
|
||
|
||
### Examples
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
PUT /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
|
||
|
||
```
|
||
|
||
> **Note:** Similar to [creating a data source](#create-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](#delete-an-existing-data-source-by-uid) or to the [API for deleting an existing data source by its name](#delete-an-existing-data-source-by-name)
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------ | ---------------------------------------------------------------------------- |
|
||
| datasources:delete | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## Delete an existing data source by uid
|
||
|
||
`DELETE /api/datasources/uid/:uid`
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------ | -------------------------------------------------------------------------------------- |
|
||
| datasources:delete | datasources:\*<br>datasources:uid:\*<br>datasources:uid:kLtEtcRGk (single data source) |
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## Delete an existing data source by name
|
||
|
||
`DELETE /api/datasources/name/:datasourceName`
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ------------------ | ---------------------------------------------------------------------------------------------- |
|
||
| datasources:delete | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## 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](#data-source-proxy-calls).
|
||
|
||
`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](#check-data-source-health).
|
||
|
||
`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.
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## 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`. 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.
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## 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](#fetch-data-source-resources).
|
||
|
||
`GET /api/datasources/:datasourceId/resources/*`
|
||
|
||
Makes a call to the resources endpoint of data source identified by the given `dashboardId`.
|
||
|
||
### Examples
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
## 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**:
|
||
|
||
```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
|
||
|
||
```
|
||
|
||
## 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**:
|
||
|
||
```http
|
||
POST /api/ds/query HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
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]
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 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. |
|