Query and resource caching API

NOTE: 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.

Enable caching for a data source

POST /api/datasources/:dataSourceUID/cache/enable

Required permissions

See note in the introduction for an explanation.

Action Scope

datasources.caching:write

datasources:*

Examples

Example Request:

POST /api/datasources/jZrmlLCGka/cache/enable HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
   "message": "Data source cache enabled",
   "dataSourceID": 1,
   "dataSourceUID": "jZrmlLCGka",
   "enabled": true,
   "ttlQueriesMs": 300000,
   "ttlResourcesMs": 300000,
   "useDefaultTTL": true,
   "defaultTTLMs": 300000,
   "created": "2023-04-21T11:49:22-04:00",
   "updated": "2023-04-24T16:30:29-04:00"
}
Status codes
Code Description

200

Cache was successfully enabled for the data source

500

Unexpected error. Refer to the body and/or server logs for more details.

Disable caching for a data source

POST /api/datasources/:dataSourceUID/cache/disable

Required permissions

See note in the introduction for an explanation.

Action Scope

datasources.caching:write

datasources:*

Examples

Example Request:

POST /api/datasources/jZrmlLCGka/cache/disable HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
   "message": "Data source cache disabled",
   "dataSourceID": 1,
   "dataSourceUID": "jZrmlLCGka",
   "enabled": false,
   "ttlQueriesMs": 300000,
   "ttlResourcesMs": 300000,
   "useDefaultTTL": true,
   "defaultTTLMs": 0,
   "created": "2023-04-21T11:49:22-04:00",
   "updated": "2023-04-24T16:30:31-04:00"
}
Status codes
Code Description

200

Cache was successfully enabled for the data source

500

Unexpected error. Refer to the body and/or server logs for more details.

Clean cache for all data sources

POST /api/datasources/:dataSourceUID/cache/clean

Will clean cached data for all data sources with caching enabled. The dataSourceUID specified will only be used to return the configuration for that data source.

Required permissions

See note in the introduction for an explanation.

Action Scope

datasources.caching:write

datasources:*

Examples

Example Request:

POST /api/datasources/jZrmlLCGka/cache/clean HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
   "message": "Data source cache cleaned",
   "dataSourceID": 1,
   "dataSourceUID": "jZrmlLCGka",
   "enabled": false,
   "ttlQueriesMs": 300000,
   "ttlResourcesMs": 300000,
   "useDefaultTTL": true,
   "defaultTTLMs": 0,
   "created": "2023-04-21T11:49:22-04:00",
   "updated": "2023-04-24T16:30:31-04:00"
}
Status codes
Code Description

200

Cache was successfully enabled for the data source

500

Unexpected error. Refer to the body and/or server logs for more details.

Update cache configuration for a data source

POST /api/datasources/:dataSourceUID/cache

Required permissions

See note in the introduction for an explanation.

Action Scope

datasources.caching:write

datasources:*

Examples

Example Request:

POST /api/datasources/jZrmlLCGka/cache HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
   "dataSourceID": 1,
   "dataSourceUID": "jZrmlLCGka",
   "enabled": true,
   "useDefaultTTL": false,
   "ttlQueriesMs": 60000,
   "ttlResourcesMs": 300000,
}
JSON Body Schema
Field name Data type Description

dataSourceID

number

The ID of the data source to configure.

dataSourceUID

string

The UID of the data source to configure.

enabled

boolean

Whether or not to enable caching for this data source.

useDefaultTTL

boolean

Whether the configured default TTL (Time-To-Live) should be used for both query and resource caching, instead of the user-specified values.

ttlQueriesMs

number

The TTL to use for query caching, in milliseconds.

ttlResourcesMs

number

The TTL to use for resource caching, in milliseconds.

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
   "message": "Data source cache settings updated",
   "dataSourceID": 1,
   "dataSourceUID": "jZrmlLCGka",
   "enabled": true,
   "useDefaultTTL": false,
   "ttlQueriesMs": 60000,
   "ttlResourcesMs": 300000,
   "defaultTTLMs": 300000,
   "created": "2023-04-21T11:49:22-04:00",
   "updated": "2023-04-24T17:03:40-04:00"
}
Status codes
Code Description

200

Cache was successfully enabled for the data source

400

Request errors (invalid json, missing or invalid fields, etc)

500

Unexpected error. Refer to the body and/or server logs for more details.

Get cache configuration for a data source

GET /api/datasources/:dataSourceUID/cache

Required permissions

See note in the introduction for an explanation.

Action Scope

datasources.caching:read

datasources:*

Examples

Example Request:

GET /api/datasources/jZrmlLCGka/cache HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
   "message": "Data source cache settings loaded",
   "dataSourceID": 1,
   "dataSourceUID": "jZrmlLCGka",
   "enabled": true,
   "useDefaultTTL": false,
   "ttlQueriesMs": 60000,
   "ttlResourcesMs": 300000,
   "defaultTTLMs": 300000,
   "created": "2023-04-21T11:49:22-04:00",
   "updated": "2023-04-24T17:03:40-04:00"
}
Status codes
Code Description

200

Cache was successfully enabled for the data source

500

Unexpected error. Refer to the body and/or server logs for more details.