Dashboard API

    The unique identifier (uid) of a dashboard can be used for uniquely identify a dashboard between multiple Grafana installs. It’s automatically generated if not provided when creating a dashboard. The uid allows having consistent URLs for accessing dashboards and when syncing dashboards between multiple Grafana installs, see for more information. This means that changing the title of a dashboard will not break any bookmarked links to that dashboard.

    The uid can have a maximum length of 40 characters.

    Create / Update dashboard

    Creates a new dashboard or updates an existing dashboard. When updating existing dashboards, if you do not define the folderId or the folderUid property, then the dashboard(s) are moved to the General folder. (You need to define only one property, not both).

    Example Request for new dashboard:

    JSON Body schema:

    • dashboard – The complete dashboard model, id = null to create a new dashboard.
    • dashboard.id – id = null to create a new dashboard.
    • dashboard.uid – Optional unique identifier when creating a dashboard. uid = null will generate a new uid.
    • folderId – The id of the folder to save the dashboard in.
    • folderUid – The UID of the folder to save the dashboard in. Overrides the folderId.
    • overwrite – Set to true if you want to overwrite existing dashboard with newer version, same dashboard title in folder or same dashboard uid.
    • message - Set a commit message for the version history.
    • refresh - Set the dashboard refresh interval. If this is lower than , then Grafana will ignore it and will enforce the minimum refresh interval.

    For adding or updating an alert rule for a dashboard panel the user should declare a dashboard.panels.alert block.

    Example Request for updating dashboard alert rule:

    1. HTTP/1.1 200 OK
    2. Content-Type: application/json; charset=UTF-8
    3. Content-Length: 78
    5. {
    6.  "dashboard":  {
    7.         "id": 104,
    8.         "panels": [
    9.             {
    10.                 "alert": {
    11.                     "alertRuleTags": {},
    12.                     "conditions": [
    13.                         {
    14.                             "evaluator": {
    15.                                 "params": [
    16.                                     25
    17.                                 ],
    18.                                 "type": "gt"
    19.                             },
    20.                             "operator": {
    21.                                 "type": "and"
    22.                             },
    23.                             "query": {
    24.                                 "params": [
    25.                                     "A",
    26.                                     "5m",
    27.                                     "now"
    28.                                 ]
    29.                             },
    30.                             "reducer": {
    31.                                 "params": [],
    32.                                 "type": "avg"
    33.                             },
    34.                             "type": "query"
    35.                         }
    36.                     ],
    37.                     "executionErrorState": "alerting",
    38.                     "for": "5m",
    39.                     "frequency": "1m",
    40.                     "handler": 1,
    41.                     "name": "Panel Title alert",
    42.                     "noDataState": "no_data",
    43.                     "notifications": []
    44.                 },
    45.                 "aliasColors": {},
    46.                 "bars": false,
    47.                 "dashLength": 10,
    48.                 "dashes": false,
    49.                 "datasource": null,
    50.                 "fieldConfig": {
    51.                     "defaults": {
    52.                         "custom": {}
    53.                     },
    54.                     "overrides": []
    55.                 },
    56.                 "fill": 1,
    57.                 "fillGradient": 0,
    58.                 "gridPos": {
    59.                     "h": 9,
    60.                     "w": 12,
    61.                     "x": 0,
    62.                     "y": 0
    63.                 },
    64.                 "hiddenSeries": false,
    65.                 "id": 2,
    66.                 "legend": {
    67.                     "avg": false,
    68.                     "current": false,
    69.                     "max": false,
    70.                     "min": false,
    71.                     "show": true,
    72.                     "total": false,
    73.                     "values": false
    74.                 },
    75.                 "lines": true,
    76.                 "linewidth": 1,
    77.                 "nullPointMode": "null",
    78.                 "options": {
    79.                     "dataLinks": []
    80.                 "percentage": false,
    81.                 "pointradius": 2,
    82.                 "points": false,
    83.                 "renderer": "flot",
    84.                 "seriesOverrides": [],
    86.                 "stack": false,
    87.                 "steppedLine": false,
    88.                 "targets": [
    89.                     {
    90.                         "refId": "A",
    91.                         "scenarioId": "random_walk"
    92.                     }
    93.                 ],
    94.                 "thresholds": [
    95.                     {
    96.                         "colorMode": "critical",
    97.                         "fill": true,
    98.                         "line": true,
    99.                         "op": "gt",
    100.                         "value": 50
    101.                     }
    102.                 ],
    103.                 "timeFrom": null,
    104.                 "timeRegions": [],
    105.                 "timeShift": null,
    106.                 "title": "Panel Title",
    107.                 "tooltip": {
    108.                     "shared": true,
    109.                     "sort": 0,
    110.                     "value_type": "individual"
    111.                 },
    112.                 "type": "graph",
    113.                 "xaxis": {
    114.                     "buckets": null,
    115.                     "mode": "time",
    116.                     "name": null,
    117.                     "show": true,
    118.                     "values": []
    119.                 },
    120.                 "yaxes": [
    121.                     {
    122.                         "format": "short",
    123.                         "label": null,
    124.                         "logBase": 1,
    125.                         "max": null,
    126.                         "min": null,
    127.                         "show": true
    128.                     },
    129.                     {
    130.                         "format": "short",
    131.                         "label": null,
    132.                         "logBase": 1,
    133.                         "max": null,
    134.                         "min": null,
    135.                         "show": true
    136.                     }
    137.                 ],
    138.                 "yaxis": {
    139.                     "align": false,
    140.                     "alignLevel": null
    141.                 }
    142.             }
    143.         ],
    144.         "title": "Update alert rule via API",
    145.         "uid": "dHEquNzGz",
    146.         "version": 1
    147.     }
    148. }

    Example Response:

    1. HTTP/1.1 200 OK
    2. Content-Type: application/json; charset=UTF-8
    3. Content-Length: 78
    5. {
    6.   "id":      1,
    7.   "uid":     "cIBgcSjkk",
    8.   "url":     "/d/cIBgcSjkk/production-overview",
    9.   "status":  "success",
    10.   "version": 1,
    11.   "slug":    "production-overview" //deprecated in Grafana v5.0
    12. }

    Status Codes:

    • 200 – Created
    • 400 – Errors (invalid json, missing or invalid fields, etc)
    • 401 – Unauthorized
    • 403 – Access denied
    • 412 – Precondition failed
    • The dashboard has been changed by someone else, status=version-mismatch
    • A dashboard with the same name in the folder already exists, status=name-exists
    • A dashboard with the same uid already exists, status=name-exists
    • The dashboard belongs to plugin <plugin title>, status=plugin-dashboard

    The response body will have the following properties:

    1. HTTP/1.1 412 Precondition Failed
    2. Content-Type: application/json; charset=UTF-8
    3. Content-Length: 97
    5.   "message": "The dashboard has been changed by someone else",
    6.   "status": "version-mismatch"
    7. }

    In case of title already exists the status property will be .

    GET /api/dashboards/uid/:uid

    Will return the dashboard given the dashboard unique identifier (uid). Information about the unique identifier of a folder containing the requested dashboard might be found in the metadata.

    Example Request:

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.   "dashboard": {
    6.     "id": 1,
    7.     "uid": "cIBgcSjkk",
    8.     "title": "Production Overview",
    9.     "tags": [ "templated" ],
    10.     "timezone": "browser",
    11.     "schemaVersion": 16,
    12.     "version": 0
    13.   },
    14.   "meta": {
    15.     "isStarred": false,
    16.     "url": "/d/cIBgcSjkk/production-overview",
    17.     "folderId": 2,
    18.     "folderUid": "l3KqBxCMz",
    19.     "slug": "production-overview" //deprecated in Grafana v5.0
    20.   }
    21. }

    Status Codes:

    • 200 – Found
    • 401 – Unauthorized
    • 403 – Access denied
    • 404 – Not found

    Delete dashboard by uid

    DELETE /api/dashboards/uid/:uid

    Will delete the dashboard given the specified unique identifier (uid).

    Example Request:

    1. DELETE /api/dashboards/uid/cIBgcSjkk HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.   "title": "Production Overview",
    6.   "message": "Dashboard Production Overview deleted",
    7.   "id": 2
    8. }

    Status Codes:

    • 200 – Deleted
    • 401 – Unauthorized
    • 403 – Access denied
    • 404 – Not found

    GET /api/dashboards/home

    Will return the home dashboard.

    Example Request:

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.   "dashboard": {
    6.     "editable":false,
    7.     "hideControls":true,
    8.     "nav":[
    9.       {
    10.         "enable":false,
    11.         "type":"timepicker"
    12.       }
    13.     ],
    14.     "style":"dark",
    15.     "tags":[],
    16.     "templating":{
    17.       "list":[
    18.       ]
    19.     },
    20.     "time":{
    21.     },
    22.     "timezone":"browser",
    23.     "title":"Home",
    24.     "version":5
    25.   },
    26.   "meta":    {
    27.     "isHome":true,
    28.     "canSave":false,
    29.     "canEdit":false,
    30.     "canStar":false,
    31.     "url":"",
    32.     "expires":"0001-01-01T00:00:00Z",
    33.     "created":"0001-01-01T00:00:00Z"
    34.   }
    35. }

    Tags for Dashboard

    GET /api/dashboards/tags

    Get all tags of dashboards

    Example Request:

    1. GET /api/dashboards/tags 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.     "term":"tag1",
    7.     "count":1
    8.   },
    9.   {
    10.     "term":"tag2",
    11.     "count":4
    12. ]

    See .