> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spidra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube

> Get YouTube videos with transcripts and top comments, channels with their videos, playlists and search results as structured data, for 1 credit per link.

Send a YouTube link to [Scrape](https://docs.spidra.io/scrape.md) or [Batch scrape](https://docs.spidra.io/batch-scrape.md) and you get the page's data as JSON: a video's views, likes, transcript and top comments, a channel's stats and videos, a playlist, or search results. Pages are read the way a signed-out visitor sees them. Each link costs 1 credit, and links that can't be read cost nothing.

## Example

```bash theme={null}
curl -X POST https://api.spidra.io/api/batch/scrape \
  -H "Authorization: Bearer $SPIDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
    "output": "json",
    "wait": true
  }'
```

The item's `result`, shortened:

```json theme={null}
{
  "type": "video",
  "id": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "channel": { "name": "Rick Astley", "handle": "@RickAstleyYT", "subscribers": 4550000, "verified": true },
  "views": 1830251888,
  "likes": 19496127,
  "commentsCount": 2460581,
  "publishDate": "2009-10-24T23:57:33-07:00",
  "duration": "3:33",
  "durationSeconds": 213,
  "category": "Music",
  "transcript": {
    "language": "en",
    "isAutoGenerated": false,
    "segmentCount": 61,
    "segments": [{ "start": 1.36, "duration": 1.68, "text": "[♪♪♪]" }],
    "text": "[♪♪♪] ♪ We're no strangers to love ♪ ..."
  },
  "comments": [{ "author": "...", "text": "...", "likes": 0, "replyCount": 0, "isPinned": false }],
  "relatedVideos": ["..."]
}
```

With `"output": "json"` and no prompt, this comes back as is, with no AI. In Markdown mode, the same data is in `structuredData` on the result.

## Links that work

| Link | Example | You get |
| - | - | - |
| Video | `youtube.com/watch?v=...`, `youtu.be/...`, `/shorts/...`, `/live/...`, `/embed/...` | The video's details, transcript, first 40 top comments and related videos |
| Channel | `youtube.com/@mkbhd`, `/channel/UC...`, `/c/name`, `/user/name` | The channel's stats and the items on its home tab |
| Channel tab | `/@mkbhd/videos`, `/shorts`, `/streams`, `/playlists`, `/posts`, `/about` | The channel's stats and that tab's items (about 60 videos, Shorts or streams) |
| Playlist | `youtube.com/playlist?list=...` | The playlist's details and its first 100 videos |
| Search | `youtube.com/results?search_query=...` (and the `sp=` filter) | Videos, channels, playlists, Shorts and posts in YouTube's order |

## Fields

**Video:** `id`, `url`, `title`, `description`, `channel` (`name`, `id`, `handle`, `url`, `subscribers`, `verified`, `isOfficialArtist`, `avatar`), `views`, `likes`, `commentsCount`, `publishDate`, `uploadDate`, `dateText`, `duration`, `durationSeconds`, `keywords`, `hashtags`, `category`, `isShort`, `isLive`, `wasLive`, `isUpcoming`, `isAgeRestricted`, `isFamilySafe`, `isUnlisted`, `availability`, `thumbnail`, `thumbnails`, `embedUrl`, `chapters`, `captionLanguages`, `transcript` (`language`, `isAutoGenerated`, timed `segments`, full `text`), `comments` (`id`, `url`, `text`, `author`, `likes`, `replyCount`, `publishedText`, `isEdited`, `isPinned`, `isHearted`) and `relatedVideos`.

**Channel:** `id`, `url`, `handle`, `name`, `description`, `verified`, `subscribers`, `videoCount`, `views`, `joinedDate`, `country`, `links`, `keywords`, `avatar`, `banner`, `rssUrl`, `tabs`, and `items` (each with `id`, `url`, `title`, `views`, `publishedText`, `duration`, `durationSeconds`, `isLive`, `thumbnail`).

**Search:** `query`, `estimatedResults`, `resultCount`, `resultCounts` (by type), and `results`, each with a `position` and the same fields as a channel item.

## Options

* **Transcript language:** add YouTube's own `cc_lang_pref` parameter to the link, such as `watch?v=...&cc_lang_pref=es`. Without it, Spidra picks English, then the video's own language, and human captions before auto-generated ones.
* **Search filters:** keep YouTube's `sp=` parameter from a filtered search link (upload date, type, duration).

## Limits

* **Signed-out only.** Age-restricted videos return their details with a note that comments and captions need a sign-in. Private and members-only videos fail and cost nothing.
* **No captions, no transcript.** Videos without captions return `transcript: null` with a note in `transcriptNote`.
* **Not available:** video or audio files, live chat, dislikes, and poll vote counts.
* **Live streams** show chat instead of comments, so comments are empty with a note.

## Templates

Ready-made [templates](https://docs.spidra.io/templates.md) for YouTube: video transcripts, video details, video comments, channel videos (Shorts and streams too), channel stats, playlist videos and search results.

> [!NOTE]
>
> Check YouTube's terms before you collect data from it. You're responsible for how you use what you collect.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.