GET Playlist by PublicId

Overview

---

The following table contains important information about the GET method in regards to receiving the playlist by using the public ID.

This version of the endpoint returns the folder selection as a structured playlistFolders array instead of the flat folders array of integers used in API V1. Each entry carries an includeFutureSubfolders flag, which marks the folder as a lock-root: when it is true, every current and future subfolder of that folder is automatically included in the playlist, without the playlist having to be edited again.

GET Playlist by PublicId
Method	GET
URL or Endpoint	/api/v2/projects/projectId/playlists/id
Headers	Authorization
Parameters	projectId, id
Body	Not Applicable

The description of the URL parameters is as follows:

URL Parameter Name	Mandatory	Type	Description
projectId	Yes	string	Unique ID of the project.
id	Yes	string	Unique ID of the playlist.

Request Body

The request does not contain a request body.

Response

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "publicId": "{publicId}",
    "title": "{title}",
    "description": "{description}",
    "playListPagePermalink": "{playListPagePermalink}",
    "playListTypeId": 0,
    "playlistDisplayTypeId": 0,
    "playlistSortOptionId": 0,
    "includeTags": [
      "{includeTag}"
    ],
    "excludeTags": [
      "{excludeTag}"
    ],
    "includeTagsState": false,
    "excludeTagsState": false,
    "excludeFlags": [
      0
    ],
    "includeFlags": [
      0
    ],
    "includeAllProjects": false,
    "includeProjects": [
      "{projectId}"
    ],
    "excludeFlagsState": false,
    "includeFlagsState": false,
    "includeTagModeId": 0,
    "excludeTagModeId": 0,
    "includeFlagModeId": 0,
    "excludeFlagModeId": 0,
    "maxVideos": 0,
    "dateFrom": "2026-08-10T15:02:46.586Z",
    "dateTo": "2026-08-10T15:02:46.586Z",
    "canEmbed": true,
    "playlistBackupState": false,
    "playlistBackupId": "{playlistBackupId}",
    "excludeWatchedVideosState": false,
    "excludeKeywords": [
      "{excludeKeyword}"
    ],
    "aspectRatios": [
      0
    ],
    "includeTagMode": {
      "id": 0,
      "name": "{name}"
    },
    "excludeTagMode": {
      "id": 0,
      "name": "{name}"
    },
    "playlistType": {
      "id": 0,
      "name": "{name}",
      "value": "{value}",
      "description": "{description}"
    },
    "playlistSortOption": {
      "id": 0,
      "name": "{name}"
    },
    "playlistDisplayType": {
      "id": "{id}",
      "name": "{name}",
      "value": "{value}"
    },
    "playlistFolders": [
      {
        "folderId": 0,
        "includeFutureSubfolders": false
      }
    ]
  },
  "resultInfo": null,
  "statusCode": 200
}

Information about the fields that appear when you receive the response are displayed in the table below.

Top-Level Properties

Field Name	Type	Description
success	boolean	If the response is successful it will return true. Otherwise will return false.
errors	array[string]	Indicates if there was an error.
messages	array[string]	Returns the response message from back-end.
result	object	Returns the response object.
publicId	string	The ID of the playlist.
title	string	The title of the playlist.
description	string	Returns information about the playlist.
playListPagePermalink	string	The permalink of the playlist page.
playListTypeId	integer	The ID of the playlist type.
playlistDisplayTypeId	integer or null	The ID of the playlist display type.
playlistSortOptionId	integer or null	The ID of the playlist sorting option.
includeTags	array[string]	An array that contains the tags included in the playlist.
excludeTags	array[string]	An array that contains the tags excluded from the playlist.
includeTagsState	boolean	Indicates whether the tags state is included.
excludeTagsState	boolean	Indicates whether the tags state is excluded.
excludeFlags	array[integer]	An array that contains the flags excluded from the playlist.
includeFlags	array[integer]	An array that contains the flags included in the playlist.
includeAllProjects	boolean	Indicates whether videos from all projects of the organization should be included.
includeProjects	array[string]	An array of project IDs whose videos are included in the playlist.
excludeFlagsState	boolean	Indicates whether the flags state is excluded.
includeFlagsState	boolean	Indicates whether the flags state is included.
includeTagModeId	integer or null	The ID of the includeTag mode.
excludeTagModeId	integer or null	The ID of the excludeTag mode.
includeFlagModeId	integer or null	The ID of the includeFlag mode.
excludeFlagModeId	integer or null	The ID of the excludeFlag mode.
maxVideos	integer or null	The maximum number of videos in the playlist.
dateFrom	string($date-time) or null	Include videos uploaded on or after this date and time.
dateTo	string($date-time) or null	Include videos uploaded on or before this date and time.
canEmbed	boolean	Indicates whether the playlist can be embedded or not.
playlistBackupState	boolean or null	Indicates whether the playlist has a backup playlist or not.
playlistBackupId	string	The unique identifier of the backup playlist.
excludeWatchedVideosState	boolean	Indicates whether the videos previously watched by the user are excluded from the playlist.
excludeKeywords	array[string]	An array of keywords; videos containing any of these keywords are excluded from the playlist.
aspectRatios	array[integer]	An array of aspect ratios; only videos that match the specified aspect ratios are included in the playlist.
includeTagMode	object	Returns the includeTag mode object.
excludeTagMode	object	Returns the excludeTag mode object.
playlistType	object	Returns the playlist type object.
playlistSortOption	object	Returns the playlist sort option object.
playlistDisplayType	object	Returns the playlist display type object.
playlistFolders	array[object]	The folder selection of the playlist as it was saved. Only the selected folders are returned, not the subfolders that are resolved from a folder marked with includeFutureSubfolders.
resultInfo	string	Returns extra information about the result.
statusCode	integer	Returns the HTTP Status Code.

includeTagMode Properties

Field Name	Type	Description
id	integer	The ID of the tag mode.
name	string	The name of the tag mode.

excludeTagMode Properties

Field Name	Type	Description
id	integer	The ID of the tag mode.
name	string	The name of the tag mode.

playlistType Properties

Field Name	Type	Description
id	integer	The ID of the playlist type.
name	string	The name of the playlist type.
value	string	The value of the playlist type.
description	string	The description of the playlist type.

playlistSortOption Properties

Field Name	Type	Description
id	integer	The ID of the playlist sort option.
name	string	The name of the playlist sort option.

playlistDisplayType Properties

Field Name	Type	Description
id	string	The ID of the playlist display type.
name	string	The name of the playlist display type.
value	string	The value of the playlist display type.

playlistFolders Properties

Field Name	Type	Description
folderId	integer	The ID of the folder whose videos are included in the playlist.
includeFutureSubfolders	boolean	When true, all current and future subfolders of this folder are included in the playlist automatically. When false, only the videos of this folder are included.

If the action is successful, the service sends back an HTTP 200 or 201 response.

Errors

For information about the errors that are common to all actions, see Common Errors:

• HTTP Status Code 400: Bad Request

• HTTP Status Code 401: Unauthorized

• HTTP Status Code 403: Forbidden

• HTTP Status Code 404: Result Not Found

• HTTP Status Code 500: Internal Server Error

• HTTP Status Code 503: Backend Fetch Failed