Implementing Playlists

1. Creating Playlists

Playlists in Grafana allow you to group dashboards and organize them into sequences for presentation or automated viewing.

Field	Description	Example
name	Name of the playlist	`"Team Dashboard Rotation"`
interval	Time interval between dashboard transitions (e.g., `10s`, `1m`)	`"30s"`
items	List of dashboards to include in the playlist	`[{ "id": 123, "order": 1 }, { "id": 456, "order": 2 }]`

Example: Creating a Playlist via API

{
  "name": "Weekly Metrics Review",
  "interval": "1m",
  "items": [
    {
      "id": 123,
      "order": 1
    },
    {
      "id": 456,
      "order": 2
    }
  ]
}

Note: The id field in each item refers to the dashboard ID in Grafana.

2. Adding Dashboards to Playlist

Property	Description	Values
playlistId	Unique identifier for the playlist	`string`
dashboardUid	Unique identifier for the dashboard to add	`string`
order	Position in the playlist (starts at 1)	`number`

Example: Adding a Dashboard to a Playlist

const playlistId = 'playlist-123';
const dashboardUid = 'dashboard-456';
const order = 1;

// API request to add dashboard to playlist
const response = await fetch(`/api/playlists/${playlistId}/dashboards`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-api-token>'
  },
  body: JSON.stringify({
    dashboardUid,
    order
  })
});

console.log('Dashboard added to playlist:', response.status);

3. Setting Playlist Interval

Property	Value	Description
playlist.interval	`30s`	Interval in seconds between playlist items
playlist.refresh	`5m`	Refresh interval for the playlist

Example: Configure Playlist Interval

{
  "playlist": {
    "interval": "60s",
    "refresh": "10m"
  }
}

Note: The interval must be a valid duration string (e.g., 30s, 1m, 5m) and is used to control how often the next item in the playlist is displayed.

4. Starting Playlist

Property	Description	Default
playlist.name	Name of the playlist	""
playlist.interval	Time interval (in seconds) to cycle through panels	15
playlist.panels	List of panel IDs to include in the playlist	[]

Example: Creating a Playlist

{
  "name": "System Dashboard Playlist",
  "interval": 30,
  "panels": [
    123,
    456,
    789
  ]
}

5. Stopping Playlist

Property	Description	Values
playlistId	Unique identifier for the playlist	`string`
status	Current status of the playlist	`active` \| `paused` \| `stopped`

Example: Stopping a Playlist via API

const response = await fetch(
  &#x27;http://localhost:3000/api/playlist/123/stop&#x27;,
  {
    method: &#x27;POST&#x27;,
    headers: {
      &#x27;Authorization&#x27;: &#x27;Bearer <token>&#x27;,
      &#x27;Content-Type&#x27;: &#x27;application/json&#x27;
    }
  }
);
const result = await response.json();
console.log(result);

Note: Stopping a playlist will pause all active dashboards in the playlist and prevent further automatic transitions.

6. Editing Playlist

Property	Description	Values	Notes
playlist.name	Name of the playlist	`string`	Required field
playlist.interval	Time interval between slides	`duration`	Default is 15s
playlist.items	List of dashboard items in the playlist	`array`	Each item has dashboard ID and optional title

Example: Update Playlist Interval

{
  "name": "My Dashboard Playlist",
  "interval": "30s",
  "items": [
    {
      "dashboardId": 1,
      "title": "Overview Dashboard"
    },
    {
      "dashboardId": 2,
      "title": "Metrics Dashboard"
    }
  ]
}

Note: Changes to the playlist are saved immediately. The updated interval will affect all viewers of the playlist.

Property	Value	Description
playlistId	`12345`	The unique identifier of the playlist
url	`/playlists/12345`	Base URL to access the playlist
embedUrl	`/playlists/12345/embed`	URL to embed the playlist in another page

Example: Generate Shareable Playlist URL

const playlistId = 12345;
const baseUrl = 'https://grafana.example.com';
const shareableUrl = `${baseUrl}/playlists/${playlistId}`;
console.log(shareableUrl); // https://grafana.example.com/playlists/12345

Note: The playlist URL can be shared with other users who have access to the Grafana instance.

Warning: Ensure that the playlist is not restricted to specific users or roles if it's intended for public sharing.

8. Using Playlists for Kiosk Mode

Playlists in Grafana can be used to create kiosk mode displays, which are ideal for public or dedicated monitoring screens. Kiosk mode provides a full-screen view of dashboards without UI elements like navigation bars or sidebars.

Setting	Description	Value
kioskMode	Enables kiosk mode for the dashboard	`true`
playlistId	ID of the playlist to use for kiosk mode	`123`

Example: Enabling Kiosk Mode via URL

https://grafana.example.com/dashboards/playlist/123?kiosk

Note: Kiosk mode is available in Grafana v9.0 and later.

9. Managing Playlists via API

Endpoint	Method	Description	Notes
/api/playlists	GET	Retrieve all playlists	Requires admin permissions
/api/playlists	POST	Create a new playlist	Body must include name and items
/api/playlists/{id}	GET	Get a specific playlist by ID
/api/playlists/{id}	PUT	Update a playlist by ID
/api/playlists/{id}	DELETE	Delete a playlist by ID

Example: Create a Playlist

{
  "name": "My Dashboard Playlist",
  "interval": "5m",
  "items": [
    {
      "id": 1,
      "type": "dashboard_by_id",
      "value": "123"
    }
  ]
}

Example: Update Playlist Items

{
  "name": "Updated Playlist",
  "interval": "10m",
  "items": [
    {
      "id": 1,
      "type": "dashboard_by_id",
      "value": "123"
    },
    {
      "id": 2,
      "type": "dashboard_by_name",
      "value": "Production Metrics"
    }
  ]
}

Note: The interval field controls how often the playlist cycles through its items. Valid values are strings like "5m", "1h", etc.

10. Setting Playlist Auto-Fit

Property	Description	Default Value	Notes
autoFit	Enables or disables auto-fitting of playlist items to the screen size	`false`	When enabled, Grafana adjusts the layout of dashboard items to fit within the playlist view
autoFitInterval	Time interval (in seconds) between auto-fitting adjustments	`30`	Applies only when `autoFit` is enabled

Example: Enabling Auto-Fit in Playlist Configuration

{
  "name": "My Dashboard Playlist",
  "autoFit": true,
  "autoFitInterval": 60
}

Note: Auto-fit is particularly useful for presentations or kiosks where dashboards need to dynamically adjust to screen sizes.