---
title: "Get Playlist by ID or Reference ID"
method: GET
path: "/accounts/{{account_id}}/playlists/{playlist_id}"
tags: ["Playlists"]
---

# Get Playlist by ID or Reference ID

`GET /accounts/{{account_id}}/playlists/{playlist_id}`

Gets a playlist object for an account, based on playlist ID or reference ID. **Note that playlists may contain up to 1000 videos. By default, only the first 20 are returned. You can use the `limit` and `offset` parameters to control how many (up to 1000) and which videos are returned for a request**

## Path parameters

- `account_id` string, required
- `playlist_id` string, required

## Query parameters

- `limit` integer
- `offset` integer
- `ad_config_id` string
- `config_id` string

## Headers

- `Authorization` string, required
- `BCOV-Policy` string, required
- `Accept` string, required

## Response `200`

200

- PlaylistResponse
  - `account_id` string — Video Cloud account id
  - `created_at` string — date/time created
  - `description` string — playlist description
  - `id` string — the playlist id
  - `name` string — the playlist name
  - `reference_id` string — the playlist reference id
  - `type` string — the playlist type: EXPLICIT or smart playlist type
  - `updated_at` string — date/time last modified
  - `video_ids` string[] — array of video ids (EXPLICIT playlists only)
  - `search` string — search string to retrieve the videos (smart playlists only)
  - `videos` Video[] — array of video maps
    - `id` string — video id
    - `name` string — video title
    - `created_at` string — when the video was created
    - `custom_fields` object — map of fieldname-value pairs
    - `cue_points` VideoCuePoints
      - `name` string — cue point name
      - `type` string — cue point type
      - `time` number — time of the cue point in seconds; example: 10.527
      - `metadata` string — optional metadata string (128 single-byte characters maximum)
      - `force-stop` boolean — whether video is force-stopped at the cue point
    - `description` string — video short description
    - `duration` number — video duration in milliseconds
    - `economics` 'AD_SUPPORTED' | 'FREE' — whether video is AD_SUPPORTED
    - `labels` unknown[] — Array of [labels](/cms/managing-videos/working-with-labels.html) for the video
      - unknown
    - `playback_rights_id` string — Associates specified EPA playback rights with video.
    - `poster_sources` VideoPosterSources[] — array of poster source maps (note that in many cases there will be one source with a src value identical to the poster value, but this array is included in case there are multiple protocols available, such as http and https)
      - `src` string — URL for a poster source image (note that in many cases there will be one source with a src value identical to the poster value, but this array is included in case there are multiple protocols available, such as http and https)
    - `poster` string — URL for the default poster source image
    - `projection` string — The mapping projection for 360° videos, e.g. "equirectangular"
    - `thumbnail_sources` VideoThumbnailSources[] — array of thumbnail source maps (note that in many cases there will be one source with a src value identical to the thumbnail value, but this array is included in case there are multiple protocols available, such as http and https)
      - `src` string — URL for a thumbnail source image (note that in many cases there will be one source with a src value identical to the thumbnail value, but this array is included in case there are multiple protocols available, such as http and https)
    - `thumbnail` string — URL for the default thumbnail source image
    - `link` VideoLink
      - `text` string — text for the link
      - `url` string — URL for the link
    - `long_description` string — video long description
    - `offline_enabled` boolean — whether video is enabled for offline viewing
    - `reference_id` string — video reference-id (must be unique within the account)
    - `tags` string[] — array of tags
    - `sources` VideoSources[] — array of video sources (renditions)
      - `avg_bitrate` number — average bitrate
      - `width` number — frame width in pixels
      - `height` number — frame height in pixels
      - `size` number — size in bytes
      - `duration` number — duration in milliseconds
      - `asset_id` string — the asset id for the source
      - `stream_name` string — the stream name for the source
      - `codec` string — the video codec
      - `container` string — the video container
      - `app_name` string — the address for rtmp streams
      - `type` string — the type (for HLS streams)
    - `text_tracks` VideoTextTracks[] — array of text track maps
      - `src` string — URL for the .vtt file
      - `sources` VideoTextTracksSources[] — array of sources for .vtt files (note that in many cases there will be one source with a src value identical to the text_tracks.src value, but this array is included in case there are multiple protocols available, such as http and https)
        - `src` string — URL for the .vtt file (note that in many cases there will be one source with a src value identical to the text_tracks.src value, but this array is included in case there are multiple protocols available, such as http and https)
      - `kind` string — kind of text track
      - `srclang` string — 2-letter language code, such as "en" or "ko"
      - `mime_type` string — mime_type for the track
      - `label` string — label for the track
      - `default` boolean — whether this is the default track
      - `in_band_metadata_track_dispatch_type` string — If this field is present, it means that references for this text track are available in the associated video's manifest
    - `transcripts` Transcription[] — array of transcription objects - can only be added on update, not creation — unresolved $ref
    - `updated_at` string — when the video was last modified
    - `variants` VideoVariant[] — array of variant objects containing multi-lingual metadata
      - `language` string — The language for this variant in the language-country code format (examples: en-US, es-ES)
      - `name` string — The title of the video in this language
      - `description` string — The video short description in this language
      - `long_description` string — The video long description in this language
      - `custom_fields` object — map of `fieldname: value` pairs, where values are for this language; values have a maximum length of 1024 single-byte characters. Note: be sure to use the **internal** name for the field, not the display name
    - `ad_keys` object — map of key/value pairs for ad requests

## Other responses

- `400` — BAD_REQUEST: DUPLICATE_PARAMETERS - The same parameter name was provided more than once in the request INVALID_SEARCH - The search parameters are not valid ILLEGAL_QUERY - The search string syntax was invalid - example ACCESS_DENIED: - ACCOUNT_ID - The account id in the policy key does not match the account in the api request <br> API - The policy key is not search-enabled when attempting to perform a search - CLIENT_GEO - The video is restricted from playing in the current geo region; the message will contain additional information about the specific issue. For more details, see the Playback API Error Reference - CLIENT_IP - The video is restricted at the current IP address <br> DOMAIN - The video is restricted from playing on the current domain - POLICY_ERROR - Error when evaluating the policy key - VIDEO_NOT_PLAYABLE - For a single video request, the video exists, but is not allowed to be played now.
- `401` — INVALID_POLICY_KEY:undefined
- `403` — ACCESS_DENIED: - ACCOUNT_ID - The account id in the policy key does not match the account in the api request - DOMAIN - The video is restricted from playing on the current domain - CLIENT_GEO - The video is restricted from playing in the current geo region; the message will contain additional information about the specific issue. For more details, see the Playback API Error Reference - CLIENT_IP - The video is restricted at the current IP address - POLICY_ERROR - Error when evaluating the policy key
- `405` — METHOD_NOT_ALLOWED:Only GET, HEAD and OPTIONS are allowed for this api.
- `500` — SERVER_ERROR:internal server error
- `502` — SERVER_ERROR:Got a bad response from a backend server
- `504` — SERVER_TIMEOUT:Either a backend server or one of the servers they rely on timed out.

---

[API](https://skmtc.dev/brightcovelearning/apis/playback-api-reference.md) · [All operations](https://skmtc.dev/brightcovelearning/apis/playback-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/brightcovelearning/playback-api-reference/revisions/c8653db137ef/schema)