Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Video API, gRPC: PlaylistService.List

Written by
Updated at November 25, 2025

Lists all playlists in a specific channel with pagination support.
Results can be filtered and sorted using the provided parameters.

gRPC request

rpc List (ListPlaylistsRequest) returns (ListPlaylistsResponse)

ListPlaylistsRequest

{
  "channel_id": "string",
  "page_size": "int64",
  "page_token": "string",
  "order_by": "string",
  "filter": "string"
}

Field

Description

channel_id

string

Required field. ID of the channel containing the playlists to list.

The maximum string length in characters is 50.

page_size

int64

The maximum number of playlists to return per page.

The maximum value is 100.

page_token

string

Page token for retrieving the next page of results.
This token is obtained from the next_page_token field in the previous ListPlaylistsResponse.

The maximum string length in characters is 15000.

order_by

string

Specifies the ordering of results.
Format is "<field> <order>" (e.g., "createdAt desc").
Default: "id asc".
Supported fields: ["id", "title", "createdAt", "updatedAt"].
Both snake_case and camelCase field names are supported.

The maximum string length in characters is 50.

filter

string

Filter expression to narrow down the list of returned playlists.
Expressions consist of terms connected by logical operators.
Values containing spaces or quotes must be enclosed in quotes (' or ")
with inner quotes being backslash-escaped.

Supported logical operators: ["AND", "OR"].
Supported comparison operators: ["=", "!=", ":"] where ":" enables substring matching.
Parentheses can be used to group logical expressions.

Example: title:'highlights' AND id='playlist-1'

Filterable fields: ["id", "title"].
Both snake_case and camelCase field names are supported.

The maximum string length in characters is 1000.

ListPlaylistsResponse

{
  "playlists": [
    {
      "id": "string",
      "channel_id": "string",
      "title": "string",
      "description": "string",
      "items": [
        {
          // Includes only one of the fields `video_id`, `episode_id`
          "video_id": "string",
          "episode_id": "string",
          // end of the list of possible fields
          "position": "int64"
        }
      ],
      "style_preset_id": "string",
      "created_at": "google.protobuf.Timestamp",
      "updated_at": "google.protobuf.Timestamp"
    }
  ],
  "next_page_token": "string"
}

Field

Description

playlists[]

Playlist

List of playlists matching the request criteria.
May be empty if no playlists match the criteria or if the channel has no playlists.

next_page_token

string

Token for retrieving the next page of results.
Empty if there are no more results available.

Playlist

Entity representing an ordered collection of videos or episodes.
Playlists allow organizing content into sequences for improved user experience.

Field

Description

id

string

Unique identifier of the playlist.

channel_id

string

Identifier of the channel where this playlist is created and managed.

title

string

Title of the playlist displayed in interfaces and players.

description

string

Detailed description of the playlist's content and purpose.

items[]

PlaylistItem

Ordered list of content items included in this playlist.

style_preset_id

string

Identifier of the style preset used in the player during playlist playback.

created_at

google.protobuf.Timestamp

Timestamp when the playlist was initially created in the system.

updated_at

google.protobuf.Timestamp

Timestamp of the last modification to the playlist or its metadata.

PlaylistItem

Represents a single item in a playlist.
Each item references either a video or an episode and specifies its position in the sequence.

Field

Description

video_id

string

Identifier of a video included in the playlist.

The maximum string length in characters is 50.

Includes only one of the fields video_id, episode_id.

Specifies the content identifier type for this playlist item.

episode_id

string

Identifier of an episode included in the playlist.

The maximum string length in characters is 50.

Includes only one of the fields video_id, episode_id.

Specifies the content identifier type for this playlist item.

position

int64

Position of this item in the playlist sequence (zero-indexed).
Determines the playback order of content in the playlist.

Acceptable values are 0 to 100, inclusive.
Previous
Get
Next
Create