Documentation

Grafana Cloud

Learn and build

Developer resources

Grafana APIs

HTTP API

Playlist HTTP API

Enterprise Open source Grafana Cloud

Playlist API

Note
Available in Grafana 12.4 and later.
This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.
This document may not contain the latest version of the API. For the most up-to-date list of available endpoints, refer to playlist.grafana.app/v1 in Swagger.

Endpoints

These are the available endpoints:

Method	Summary	URI
GET	List Playlists	`/apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists`
GET	Get a Playlist	`/apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists/{name}`
POST	Create a Playlist	`/apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists`
PUT	Update a Playlist	`/apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists/{name}`
DELETE	Delete a Playlist	`/apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists/{name}`

List Playlists

GET /apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists

Lists all playlists in the specified namespace.

Path parameters:

{namespace}: To learn more about which namespace to use, refer to the API overview.

Example request

The following example shows a request to list playlists:

GET /apis/playlist.grafana.app/v1/namespaces/default/playlists HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Example response

The following example shows the response:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "PlaylistList",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {},
  "items": [
    {
      "kind": "Playlist",
      "apiVersion": "playlist.grafana.app/v1",
      "metadata": {
        "name": "my-playlist-uid",
        "namespace": "default",
        "resourceVersion": "1234567890",
        "creationTimestamp": "2024-01-15T10:30:00Z"
      },
      "spec": {
        "title": "My Playlist",
        "interval": "5m",
        "items": [
          {
            "type": "dashboard_by_uid",
            "value": "dashboard-uid-1"
          },
          {
            "type": "dashboard_by_tag",
            "value": "important"
          }
        ]
      }
    }
  ]
}

Status codes

200: OK
401: Unauthorized
403: Access denied

Get a Playlist

GET /apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists/{name}

Retrieves a specific playlist by name.

Path parameters:

{namespace}: To learn more about which namespace to use, refer to the API overview.
{name}: The UID of the playlist.

Example request

The following example shows a request to get a playlist:

GET /apis/playlist.grafana.app/v1/namespaces/default/playlists/my-playlist-uid HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Example response

The following example shows the response:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-playlist-uid",
    "namespace": "default",
    "resourceVersion": "1234567890",
    "creationTimestamp": "2024-01-15T10:30:00Z"
  },
  "spec": {
    "title": "My Playlist",
    "interval": "5m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_tag",
        "value": "important"
      }
    ]
  }
}

Status codes

200: Found
401: Unauthorized
403: Access denied
404: Playlist not found

Create a Playlist

POST /apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists

Creates a new playlist.

Path parameters:

{namespace}: To learn more about which namespace to use, refer to the API overview.

Example request

The following example shows a request to create a playlist:

POST /apis/playlist.grafana.app/v1/namespaces/default/playlists HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-new-playlist-uid"
  },
  "spec": {
    "title": "My New Playlist",
    "interval": "5m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_tag",
        "value": "monitoring"
      }
    ]
  }
}

Example response

The following example shows the response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-new-playlist-uid",
    "namespace": "default",
    "resourceVersion": "1234567891",
    "creationTimestamp": "2024-01-15T10:35:00Z"
  },
  "spec": {
    "title": "My New Playlist",
    "interval": "5m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_tag",
        "value": "monitoring"
      }
    ]
  }
}

Status codes

201: Created
400: Errors (invalid JSON)
401: Unauthorized
403: Access denied
409: Conflict (a playlist with the same metadata.name already exists)

Update a Playlist

PUT /apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists/{name}

Updates an existing playlist. Provide the entire playlist, including metadata.resourceVersion from the latest version you read.

Path parameters:

{namespace}: To learn more about which namespace to use, refer to the API overview.
{name}: The UID of the playlist.

Example request

The following example shows a request to update a playlist:

PUT /apis/playlist.grafana.app/v1/namespaces/default/playlists/my-playlist-uid HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-playlist-uid",
    "namespace": "default",
    "resourceVersion": "1234567890"
  },
  "spec": {
    "title": "My Updated Playlist",
    "interval": "10m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-2"
      },
      {
        "type": "dashboard_by_tag",
        "value": "updated-tag"
      }
    ]
  }
}

Example response

The following example shows the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-playlist-uid",
    "namespace": "default",
    "resourceVersion": "1234567892",
    "creationTimestamp": "2024-01-15T10:30:00Z"
  },
  "spec": {
    "title": "My Updated Playlist",
    "interval": "10m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-2"
      },
      {
        "type": "dashboard_by_tag",
        "value": "updated-tag"
      }
    ]
  }
}

Status codes

200: Updated
400: Errors (invalid JSON)
401: Unauthorized
403: Access denied
404: Playlist not found
409: Conflict (the playlist changed since you read it)
422: Invalid playlist, for example because metadata.resourceVersion is missing

Delete a Playlist

DELETE /apis/playlist.grafana.app/v1/namespaces/{namespace}/playlists/{name}

Deletes a playlist.

Path parameters:

{namespace}: To learn more about which namespace to use, refer to the API overview.
{name}: The UID of the playlist.

Example request

The following example shows a request to delete a playlist:

DELETE /apis/playlist.grafana.app/v1/namespaces/default/playlists/my-playlist-uid HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Example response

The following example shows the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {},
  "status": "Success",
  "code": 200
}

Status codes

200: Deleted
401: Unauthorized
403: Access denied
404: Playlist not found

Playlist Item Types

Playlist items support three types:

dashboard_by_uid: Include a specific dashboard by its UID
dashboard_by_tag: Include all dashboards with a specific tag
dashboard_by_id: (Deprecated) Include a dashboard by internal ID

Was this page helpful?

Email docs@grafana.com

Help and support

Community

Playlist API

Endpoints

List Playlists

Example request

Example response

Status codes

Get a Playlist

Example request

Example response

Status codes

Create a Playlist

Example request

Example response

Status codes

Update a Playlist

Example request

Example response

Status codes

Delete a Playlist

Example request

Example response

Status codes

Playlist Item Types

Was this page helpful?

Still have questions?

Get every update

Playlist API

Endpoints

List Playlists

Example request

Example response

Status codes

Get a Playlist

Example request

Example response

Status codes

Create a Playlist

Example request

Example response

Status codes

Update a Playlist

Example request

Example response

Status codes

Delete a Playlist

Example request

Example response

Status codes

Playlist Item Types

Was this page helpful?

Related resources from Grafana Labs