# Get playlist



<MethodPage method="GET" path="/v1/playlists/{id}" credits={1}>
  <MethodSignature name="getPlaylist" args={[{ name: "id" }, { name: "query", optional: true }, { name: "options", optional: true }]} returns="Playlist" />

  Returns playlist overview plus the initial page of video items. Use `next_cursor` with [List playlist videos](/playlists/videos) for later pages.

  <Security permission="transcripts:read" />

  <SchemaGroup title="Parameters">
    <SchemaField name="id" type="string" location="path">
      Playlist ID (`PL...`) or a full YouTube playlist URL.
    </SchemaField>

    <SchemaField name="required_country" type="string" optional location="query">
      ISO country hint used when region availability matters.
    </SchemaField>
  </SchemaGroup>

  <SchemaGroup title="Returns" id="returns">
    <SchemaField name="playlist_id" type="string">
      Canonical playlist ID.
    </SchemaField>

    <SchemaField name="title" type="string">
      Playlist title.
    </SchemaField>

    <SchemaField name="description" type="string">
      Playlist description.
    </SchemaField>

    <SchemaField name="video_count" type="number">
      Total videos in the playlist.
    </SchemaField>

    <SchemaField name="view_count_text" type="string" optional>
      Display string for views.
    </SchemaField>

    <SchemaField name="author" type="string">
      Owner channel name.
    </SchemaField>

    <SchemaField name="thumbnails" type="Thumbnail[]">
      Artwork at one or more sizes.
    </SchemaField>

    <SchemaField name="videos" type="PlaylistVideo[]">
      First page of items, including `video_id`, `title`, `index`, and duration.
    </SchemaField>

    <SchemaField name="has_more" type="boolean">
      Whether another page is available.
    </SchemaField>

    <SchemaField name="next_cursor" type="string | null">
      Opaque cursor for the next page.
    </SchemaField>
  </SchemaGroup>

  <MethodSamples>
    <LanguageSample language="TypeScript">
      ```ts
      const id = "PL-_QwjtlyjHZRRt4AQnQtYFxbiVP-oyuF";
      const response = await fetch(`https://api.ytapi.dev/v1/playlists/${id}`, {
        headers: {
          Authorization: `Bearer ${process.env.YT_API_KEY}`,
        },
      });

      const playlist = await response.json();
      console.log(playlist.title, playlist.next_cursor);
      ```
    </LanguageSample>

    <LanguageSample language="Python">
      ```python
      import os
      import requests

      playlist_id = "PL-_QwjtlyjHZRRt4AQnQtYFxbiVP-oyuF"
      response = requests.get(
          f"https://api.ytapi.dev/v1/playlists/{playlist_id}",
          headers={"Authorization": f"Bearer {os.environ['YT_API_KEY']}"},
      )

      print(response.json())
      ```
    </LanguageSample>

    <LanguageSample language="cURL">
      ```bash
      curl -X GET "https://api.ytapi.dev/v1/playlists/PL-_QwjtlyjHZRRt4AQnQtYFxbiVP-oyuF" \
        -H "Authorization: Bearer $YT_API_KEY"
      ```
    </LanguageSample>

    <LanguageSample language="Go">
      ```go
      package main

      import (
      	"fmt"
      	"net/http"
      	"os"
      )

      func main() {
      	url := "https://api.ytapi.dev/v1/playlists/PL-_QwjtlyjHZRRt4AQnQtYFxbiVP-oyuF"
      	req, _ := http.NewRequest("GET", url, nil)
      	req.Header.Set("Authorization", "Bearer "+os.Getenv("YT_API_KEY"))

      	resp, err := http.DefaultClient.Do(req)
      	if err != nil {
      		panic(err)
      	}
      	defer resp.Body.Close()
      	fmt.Println(resp.Status)
      }
      ```
    </LanguageSample>

    <ResponseExample status={200}>
      ```json
      {
        "playlist_id": "PL-_QwjtlyjHZRRt4AQnQtYFxbiVP-oyuF",
        "title": "Pomodoro 25-5 / SWM",
        "description": "Study with me 25-5 pomodoro sessions and lofi beats.",
        "video_count": 94,
        "view_count_text": "25,616 views",
        "author": "Carrot TD",
        "thumbnails": [
          {
            "url": "https://i.ytimg.com/vi/6gMEMYh5HL8/hqdefault.jpg",
            "width": 480,
            "height": 360
          }
        ],
        "videos": [
          {
            "video_id": "6gMEMYh5HL8",
            "title": "3-HOUR STUDY WITH ME / calm lofi / Pomodoro 25-5",
            "index": 1,
            "length_seconds": 10800,
            "length_text": "3:00:00",
            "author": "Carrot TD"
          }
        ],
        "has_more": true,
        "next_cursor": "yt_e48bb6856a23e4e42efc"
      }
      ```
    </ResponseExample>
  </MethodSamples>
</MethodPage>