# Get playlist

Fetch playlist metadata and videos with pagination. Dates retain displayed text or are omitted. Rounded numeric counts are marked approximate.

- Platform: [YouTube](https://docs.upscrape.com/docs/platforms/youtube)
- Capability ID: `youtube.playlist.get`
- Cost: 1 credit per request
- Maximum runtime: 60 seconds
- Execute endpoint: `POST https://data.upscrape.com/execute`

## Request

Use the exact public capability ID in the shared execute envelope.

```bash
curl --request POST \
  --url https://data.upscrape.com/execute \
  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: wait=30" \
  --data '{
  "input": {
    "limit": 10,
    "max_pages": 1,
    "url": "PLAqhIrjkxbuWI23v9cThsA9GvCAUhRvKZ"
  },
  "capability": "youtube.playlist.get"
}'
```

## Input


| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | No | Maximum number of results to return. From 1 to 500. Default: `100`. |
| `max_pages` | `integer` | No | Maximum number of result pages to fetch. From 1 to 100. Default: `5`. |
| `url` | `string` | Yes | YouTube playlist URL or playlist ID |

### Example input

```json
{
  "limit": 10,
  "max_pages": 1,
  "url": "PLAqhIrjkxbuWI23v9cThsA9GvCAUhRvKZ"
}
```

## Response

Successful output is returned in `results[0].data`.

Raw platform output is intentionally open-ended and may evolve with the upstream source.

### Illustrative sample output

This example shows one response. Values and optional fields vary with the data available.

```json
{
  "has_more": false,
  "is_editable": false,
  "last_updated": "Last updated on Jun 9, 2024",
  "owner": "Andrej Karpathy",
  "owner_channel_id": "UCXUPKJO5MZQN11PqgIvyuvQ",
  "pages": 1,
  "playlist_id": "PLAqhIrjkxbuWI23v9cThsA9GvCAUhRvKZ",
  "thumbnails": [
    {
      "height": 94,
      "url": "https://i.ytimg.com/vi/VMj-3S1tku0/hqdefault.jpg?sqp=-oaymwEWCKgBEF5IWvKriqkDCQgBFQAAiEIYAQ==&rs=AOn4CLB2Op623ufQGhBzpdmt6ovG3_J-Tg",
      "width": 168
    },
    {
      "height": 110,
      "url": "https://i.ytimg.com/vi/VMj-3S1tku0/hqdefault.jpg?sqp=-oaymwEWCMQBEG5IWvKriqkDCQgBFQAAiEIYAQ==&rs=AOn4CLB8mnZInXcm0G9Ug_Ry5sc6NY6HmA",
      "width": 196
    },
    {
      "height": 138,
      "url": "https://i.ytimg.com/vi/VMj-3S1tku0/hqdefault.jpg?sqp=-oaymwEXCPYBEIoBSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLCe-ObbwJ6qnfCEYl3iQjTKcjNKRQ",
      "width": 246
    }
  ],
  "title": "Neural Networks: Zero to Hero",
  "total_videos_text": "10 videos",
  "total_views_text": "3,178,754 views",
  "url": "https://www.youtube.com/playlist?list=PLAqhIrjkxbuWI23v9cThsA9GvCAUhRvKZ",
  "video_count": 10,
  "videos": [
    {
      "channel": "Andrej Karpathy",
      "duration": "2:25:52",
      "index": 1,
      "is_playable": true,
      "thumbnails": [
        {
          "height": 94,
          "url": "https://i.ytimg.com/vi/VMj-3S1tku0/hqdefault.jpg?sqp=-[redacted:token]&rs=AOn4CLANKRlma8t_6suMaQQeluqO_rIi1A",
          "width": 168
        },
        {
          "height": 110,
          "url": "https://i.ytimg.com/vi/VMj-3S1tku0/hqdefault.jpg?sqp=-[redacted:token]&rs=AOn4CLCGj5_X_S6heDlwv-aZPswkWjPA0g",
          "width": 196
        },
        {
          "height": 138,
          "url": "https://i.ytimg.com/vi/VMj-3S1tku0/hqdefault.jpg?sqp=-[redacted:token]==&rs=AOn4CLCXO28zt5LWW5gxohv9TRcz9gSVDA",
          "width": 246
        }
      ],
      "title": "The spelled-out intro to neural networks and backpropagation: building micrograd",
      "video_id": "VMj-3S1tku0"
    },
    {
      "channel": "Andrej Karpathy",
      "duration": "1:57:45",
      "index": 2,
      "is_playable": true,
      "thumbnails": [
        {
          "height": 94,
          "url": "https://i.ytimg.com/vi/PaCmpygFfXo/hqdefault.jpg?sqp=-[redacted:token]&rs=AOn4CLAIKvVhG_WMZzYYqxo5eb3-Y6AXMw",
          "width": 168
        },
        {
          "height": 110,
          "url": "https://i.ytimg.com/vi/PaCmpygFfXo/hqdefault.jpg?sqp=-[redacted:token]&rs=AOn4CLBCNBf_IYMCCseYVC5e0M605B96uA",
          "width": 196
        },
        {
          "height": 138,
          "url": "https://i.ytimg.com/vi/PaCmpygFfXo/hqdefault.jpg?sqp=-[redacted:token]==&rs=AOn4CLAeNwcwHd21b_0fERSPOriNYrWnUQ",
          "width": 246
        }
      ],
      "title": "The spelled-out intro to language modeling: building makemore",
      "video_id": "PaCmpygFfXo"
    },
    {
      "channel": "Andrej Karpathy",
      "duration": "1:15:40",
      "index": 3,
      "is_playable": true,
      "thumbnails": [
        {
          "height": 94,
          "url": "https://i.ytimg.com/vi/TCH_1BHY58I/hqdefault.jpg?sqp=-[redacted:token]&rs=AOn4CLBtHwoPJHZc413cxmAqSkEfIdn3Ig",
          "width": 168
        },
        {
          "height": 110,
          "url": "https://i.ytimg.com/vi/TCH_1BHY58I/hqdefault.jpg?sqp=-[redacted:token]&rs=AOn4CLALpfrU3EXRW5BcIamGzjDAzvgzsA",
          "width": 196
        },
        {
          "height": 138,
          "url": "https://i.ytimg.com/vi/TCH_1BHY58I/hqdefault.jpg?sqp=-[redacted:token]==&rs=AOn4CLAHg1bSakbEadmofBmsSGTNfsyVmQ",
          "width": 246
        }
      ],
      "title": "Building makemore Part 2: MLP",
      "video_id": "TCH_1BHY58I"
    }
  ]
}
```
### Illustrative output fields

Derived from the sample above for orientation only. These fields are not a fixed response schema.

| Path | Observed type | Example |
| --- | --- | --- |
| `has_more` | `boolean` | false |
| `is_editable` | `boolean` | false |
| `last_updated` | `string` | Last updated on Jun 9, 2024 |
| `owner` | `string` | Andrej Karpathy |
| `owner_channel_id` | `string` | UCXUPKJO5MZQN11PqgIvyuvQ |
| `pages` | `integer` | 1 |
| `playlist_id` | `string` | PLAqhIrjkxbuWI23v9cThsA9GvCAUhRvKZ |
| `thumbnails` | `array` | 3 items |
| `thumbnails` | `array` | 3 items |
| `title` | `string` | Neural Networks: Zero to Hero |
| `total_videos_text` | `string` | 10 videos |
| `total_views_text` | `string` | 3,178,754 views |
| `url` | `string` | https://www.youtube.com/playlist?list=PLAqhIrjkxbuWI23v9cThsA9GvCAUhRvKZ |
| `video_count` | `integer` | 10 |
| `videos` | `array` | 3 items |
| `videos` | `array` | 3 items |

## Execution behavior

A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job.

## Related documentation

- [Authentication](https://docs.upscrape.com/docs/api/authentication)
- [Jobs and results](https://docs.upscrape.com/docs/api/jobs)
- [Errors and retries](https://docs.upscrape.com/docs/api/errors)
- [Idempotency](https://docs.upscrape.com/docs/api/idempotency)