Dashboard Versions

Get all dashboard versions

Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the new dashboard versions API.

Query parameters:

  • limit - Maximum number of results to return
  • start - Version to start from when returning queries

GET /api/dashboards/id/:dashboardId/versions

Gets all existing dashboard versions for the dashboard with the given dashboardId.

Example request for getting all dashboard versions:

  1. GET /api/dashboards/id/1/versions?limit=2?start=0 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 428
  5. [
  6.   {
  7.     "id": 2,
  8.     "dashboardId": 1,
  9.     "parentVersion": 1,
  10.     "restoredFrom": 0,
  11.     "version": 2,
  12.     "created": "2017-06-08T17:24:33-04:00",
  13.     "createdBy": "admin",
  14.     "message": "Updated panel title"
  15.   },
  16.   {
  17.     "id": 1,
  18.     "dashboardId": 1,
  19.     "parentVersion": 0,
  20.     "restoredFrom": 0,
  21.     "version": 1,
  22.     "created": "2017-06-08T17:23:33-04:00",
  23.     "createdBy": "admin",
  24.     "message": "Initial save"
  25.   }
  26. ]

Status Codes:

  • 200 - Ok
  • 400 - Errors
  • 401 - Unauthorized
  • 404 - Dashboard version not found

Get all dashboard versions by dashboard UID

Query parameters:

  • limit - Maximum number of results to return
  • start - Version to start from when returning queries

GET /api/dashboards/uid/:uid/versions

Gets all existing dashboard versions for the dashboard with the given uid.

Example request for getting all dashboard versions:

  1. GET /api/dashboards/uid/QA7wKklGz/versions?limit=2?start=0 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 428
  5. [
  6.   {
  7.     "id": 2,
  8.     "dashboardId": 1,
  9.     "uid": "QA7wKklGz",
  10.     "parentVersion": 1,
  11.     "restoredFrom": 0,
  12.     "version": 2,
  13.     "created": "2017-06-08T17:24:33-04:00",
  14.     "createdBy": "admin",
  15.     "message": "Updated panel title"
  16.   },
  17.   {
  18.     "id": 1,
  19.     "dashboardId": 1,
  20.     "uid": "QA7wKklGz",
  21.     "parentVersion": 0,
  22.     "restoredFrom": 0,
  23.     "version": 1,
  24.     "created": "2017-06-08T17:23:33-04:00",
  25.     "createdBy": "admin",
  26.     "message": "Initial save"
  27.   }
  28. ]

Status Codes:

  • 200 - Ok
  • 400 - Errors
  • 401 - Unauthorized
  • 404 - Dashboard version not found

Get dashboard version

Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the new get dashboard version API.

GET /api/dashboards/id/:dashboardId/versions/:version

Get the dashboard version with the given version, for the dashboard with the given id.

Example request for getting a dashboard version:

  1. GET /api/dashboards/id/1/versions/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 1300
  5. {
  6.   "id": 1,
  7.   "dashboardId": 1,
  8.   "parentVersion": 0,
  9.   "restoredFrom": 0,
  10.   "version": 1,
  11.   "created": "2017-04-26T17:18:38-04:00",
  12.   "message": "Initial save",
  13.   "data": {
  14.     "annotations": {
  15.       "list": [
  17.       ]
  18.     },
  19.     "editable": true,
  20.     "gnetId": null,
  21.     "graphTooltip": 0,
  22.     "id": 1,
  23.     "links": [
  25.     ],
  26.     "rows": [
  27.       {
  28.         "collapse": false,
  29.         "height": "250px",
  30.         "panels": [
  32.         ],
  33.         "repeat": null,
  34.         "repeatIteration": null,
  35.         "repeatRowId": null,
  36.         "showTitle": false,
  37.         "title": "Dashboard Row",
  38.         "titleSize": "h6"
  39.       }
  40.     ],
  41.     "schemaVersion": 14,
  42.     "style": "dark",
  43.     "tags": [
  45.     ],
  46.     "templating": {
  47.       "list": [
  49.       ]
  50.     },
  51.     "time": {
  52.       "from": "now-6h",
  53.       "to": "now"
  54.     },
  55.     "timepicker": {
  56.       "refresh_intervals": [
  57.         "5s",
  58.         "10s",
  59.         "30s",
  60.         "1m",
  61.         "5m",
  62.         "15m",
  63.         "30m",
  64.         "1h",
  65.         "2h",
  66.         "1d"
  67.       ],
  68.       "time_options": [
  69.         "5m",
  70.         "15m",
  71.         "1h",
  72.         "6h",
  73.         "12h",
  74.         "24h",
  75.         "2d",
  76.         "7d",
  77.         "30d"
  78.       ]
  79.     },
  80.     "timezone": "browser",
  81.     "title": "test",
  82.     "version": 1
  83.   },
  84.   "createdBy": "admin"
  85. }

Status Codes:

  • 200 - Ok
  • 401 - Unauthorized
  • 404 - Dashboard version not found

Get dashboard version by dashboard UID

GET /api/dashboards/uid/:uid/versions/:version

Get the dashboard version with the given version, for the dashboard with the given UID.

Example request for getting a dashboard version:

  1. GET /api/dashboards/id/1/versions/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 1300
  5. {
  6.   "id": 1,
  7.   "dashboardId": 1,
  8.   "uid": "QA7wKklGz",
  9.   "parentVersion": 0,
  10.   "restoredFrom": 0,
  11.   "version": 1,
  12.   "created": "2017-04-26T17:18:38-04:00",
  13.   "message": "Initial save",
  14.   "data": {
  15.     "annotations": {
  16.       "list": [
  18.       ]
  19.     },
  20.     "editable": true,
  21.     "gnetId": null,
  22.     "graphTooltip": 0,
  23.     "id": 1,
  24.     "links": [
  26.     ],
  27.     "rows": [
  28.       {
  29.         "collapse": false,
  30.         "height": "250px",
  31.         "panels": [
  33.         ],
  34.         "repeat": null,
  35.         "repeatIteration": null,
  36.         "repeatRowId": null,
  37.         "showTitle": false,
  38.         "title": "Dashboard Row",
  39.         "titleSize": "h6"
  40.       }
  41.     ],
  42.     "schemaVersion": 14,
  43.     "style": "dark",
  44.     "tags": [
  46.     ],
  47.     "templating": {
  48.       "list": [
  50.       ]
  51.     },
  52.     "time": {
  53.       "from": "now-6h",
  54.       "to": "now"
  55.     },
  56.     "timepicker": {
  57.       "refresh_intervals": [
  58.         "5s",
  59.         "10s",
  60.         "30s",
  61.         "1m",
  62.         "5m",
  63.         "15m",
  64.         "30m",
  65.         "1h",
  66.         "2h",
  67.         "1d"
  68.       ],
  69.       "time_options": [
  70.         "5m",
  71.         "15m",
  72.         "1h",
  73.         "6h",
  74.         "12h",
  75.         "24h",
  76.         "2d",
  77.         "7d",
  78.         "30d"
  79.       ]
  80.     },
  81.     "timezone": "browser",
  82.     "title": "test",
  83.     "version": 1
  84.   },
  85.   "createdBy": "admin"
  86. }

Status Codes:

  • 200 - Ok
  • 401 - Unauthorized
  • 404 - Dashboard version not found

Restore dashboard

Warning: This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the new restore dashboard API.

POST /api/dashboards/id/:dashboardId/restore

Restores a dashboard to a given dashboard version.

Example request for restoring a dashboard version:

  1. POST /api/dashboards/id/1/restore
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  6. {
  7.   "version": 1
  8. }

JSON body schema:

  • version - The dashboard version to restore to

Example response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 67
  5. {
  6.   "slug": "my-dashboard",
  7.   "status": "success",
  8.   "version": 3
  9. }

JSON response body schema:

  • slug - the URL friendly slug of the dashboard’s title
  • status - whether the restoration was successful or not
  • version - the new dashboard version, following the restoration

Status codes:

  • 200 - OK
  • 401 - Unauthorized
  • 404 - Not found (dashboard not found or dashboard version not found)
  • 500 - Internal server error (indicates issue retrieving dashboard tags from database)

Example error response

  1. HTTP/1.1 404 Not Found
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 46
  5. {
  6.   "message": "Dashboard version not found"
  7. }

JSON response body schema:

  • message - Message explaining the reason for the request failure.

Restore dashboard by dashboard UID

POST /api/dashboards/uid/:uid/restore

Restores a dashboard to a given dashboard version using uid.

Example request for restoring a dashboard version:

  1. POST /api/dashboards/uid/QA7wKklGz/restore
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  6. {
  7.   "version": 1
  8. }

JSON body schema:

  • version - The dashboard version to restore to

Example response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 67
  5. {
  6.   "id": 70,
  7.   "slug": "my-dashboard",
  8.   "status": "success",
  9.   "uid": "QA7wKklGz",
  10.   "url": "/d/QA7wKklGz/my-dashboard",
  11.   "version": 3
  12. }

JSON response body schema:

  • slug - the URL friendly slug of the dashboard’s title
  • status - whether the restoration was successful or not
  • version - the new dashboard version, following the restoration

Status codes:

  • 200 - OK
  • 401 - Unauthorized
  • 404 - Not found (dashboard not found or dashboard version not found)
  • 500 - Internal server error (indicates issue retrieving dashboard tags from database)

Example error response

  1. HTTP/1.1 404 Not Found
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 46
  5. {
  6.   "message": "Dashboard version not found"
  7. }

JSON response body schema:

  • message - Message explaining the reason for the request failure.

Compare dashboard versions

POST /api/dashboards/calculate-diff

Compares two dashboard versions by calculating the JSON diff of them.

Example request:

  1. POST /api/dashboards/calculate-diff HTTP/1.1
  2. Accept: text/html
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  6. {
  7.   "base": {
  8.     "dashboardId": 1,
  9.     "version": 1
  10.   },
  11.   "new": {
  12.     "dashboardId": 1,
  13.     "version": 2
  14.   },
  15.   "diffType": "json"
  16. }

JSON body schema:

  • base - an object representing the base dashboard version
  • new - an object representing the new dashboard version
  • diffType - the type of diff to return. Can be “json” or “basic”.

Example response (JSON diff):

  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=UTF-8
  4. <p id="l1" class="diff-line diff-json-same">
  5.   <!-- Diff omitted -->
  6. </p>

The response is a textual representation of the diff, with the dashboard values being in JSON, similar to the diffs seen on sites like GitHub or GitLab.

Status Codes:

  • 200 - Ok
  • 400 - Bad request (invalid JSON sent)
  • 401 - Unauthorized
  • 404 - Not found

Example response (basic diff):

  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=UTF-8
  4. <div class="diff-group">
  5.   <!-- Diff omitted -->
  6. </div>

The response here is a summary of the changes, derived from the diff between the two JSON objects.

Status Codes:

  • 200 - OK
  • 400 - Bad request (invalid JSON sent)
  • 401 - Unauthorized
  • 404 - Not found