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

# YouTube Scraper by ScrapeBadger — Overview

> Scrape YouTube videos, Shorts, channels, playlists, comments, transcripts, trending, and community posts across regions with structured JSON responses.

## Scraper API for YouTube

Search YouTube, pull full **video and Shorts detail**, fetch comments and replies, export **transcripts** (SRT/VTT/plain text), enumerate a channel's videos, shorts, streams, playlists, and community posts, and retrieve trending feeds, hashtags, and playlists — from the world's largest video platform. The API handles authentication, anti-bot bypass, and region routing automatically.

## Key Features

<CardGroup cols={3}>
  <Card title="Widest Coverage" icon="layer-group">
    39 endpoints — videos, Shorts, channels, playlists, comments, transcripts, trending, hashtags, community posts, and music search.
  </Card>

  <Card title="Transcripts & Captions" icon="closed-captioning">
    The [`/v1/youtube/videos/{id}/transcript`](/api-reference/endpoint/youtube/video-transcript) endpoint returns timed segments plus ready-to-use **SRT**, **VTT**, and full-text exports.
  </Card>

  <Card title="Anti-Bot Bypass" icon="shield-halved">
    Automatic session management, Chrome TLS impersonation, and fingerprint rotation to avoid blocks.
  </Card>

  <Card title="Rich Video Data" icon="video">
    Views, likes, chapters, heatmap (most-replayed), keywords, hashtags, live details, and streaming formats.
  </Card>

  <Card title="Region & Language" icon="globe">
    Target any content region with `gl` and any UI language with `hl` for accurate, localized results.
  </Card>

  <Card title="SDK Support" icon="code">
    First-class support via the ScrapeBadger Node.js and Python SDKs.
  </Card>
</CardGroup>

## Regions & Languages

YouTube results are localized by **content region** and **UI language**. Two query parameters control this on most endpoints:

| Parameter | Meaning | Example |
| - | - | - |
| `gl` | Content region (ISO 3166-1 alpha-2 country code) | `US`, `GB`, `DE`, `JP` |
| `hl` | UI / interface language (BCP-47 language code) | `en`, `de`, `fr`, `ja` |

<Tip>
  If omitted, `gl` defaults to `US` and `hl` defaults to `en`. Use the free [`/v1/youtube/regions`](/api-reference/endpoint/youtube/resolve-channel) and [`/v1/youtube/languages`](/api-reference/endpoint/youtube/resolve-channel) reference endpoints to fetch the full list of valid codes programmatically.
</Tip>

## Pagination

YouTube list endpoints do **not** use page numbers. Every paginated response includes a `continuation` token; pass it back as the `continuation` query parameter to fetch the next page. When `continuation` is `null`, you have reached the end.

## Quick Start

<CodeGroup>
  ```javascript Node.js theme={null}
  import ScrapeBadger from "scrapebadger";

  const client = new ScrapeBadger({ apiKey: "YOUR_API_KEY" });

  const results = await client.youtube.search({
    query: "lofi hip hop",
    gl: "US",
    hl: "en",
  });

  console.log(results.results);
  ```

  ```python Python theme={null}
  from scrapebadger import ScrapeBadger

  client = ScrapeBadger(api_key="YOUR_API_KEY")

  results = client.youtube.search(
      query="lofi hip hop",
      gl="US",
      hl="en",
  )

  print(results.results)
  ```

  ```bash cURL theme={null}
  curl "https://scrapebadger.com/v1/youtube/search?query=lofi+hip+hop&gl=US&hl=en" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

## Endpoints

### Search & Discovery

| Endpoint | Method | Description |
| - | - | - |
| [`/v1/youtube/search`](/api-reference/endpoint/youtube/search) | GET | Search videos, channels, playlists, or movies |
| [`/v1/youtube/autocomplete`](/api-reference/endpoint/youtube/search) | GET | Keyword autocomplete suggestions |
| [`/v1/youtube/trending`](/api-reference/endpoint/youtube/trending) | GET | Trending feed (Now / Music / Gaming / Movies) |
| [`/v1/youtube/trending/shorts`](/api-reference/endpoint/youtube/trending) | GET | Trending Shorts shelf |
| [`/v1/youtube/hashtags/{tag}`](/api-reference/endpoint/youtube/hashtag) | GET | Videos under a hashtag |
| [`/v1/youtube/home`](/api-reference/endpoint/youtube/trending) | GET | Guest home / recommendations feed |
| [`/v1/youtube/music/search`](/api-reference/endpoint/youtube/music-search) | GET | YouTube Music search (songs, albums, artists) |

### Videos & Shorts

| Endpoint | Method | Description |
| - | - | - |
| [`/v1/youtube/videos/{video_id}`](/api-reference/endpoint/youtube/get-video) | GET | Full video detail |
| [`/v1/youtube/videos/batch`](/api-reference/endpoint/youtube/get-video) | POST | Up to 50 videos in one request |
| [`/v1/youtube/videos/{video_id}/related`](/api-reference/endpoint/youtube/get-video) | GET | Related / recommended videos |
| [`/v1/youtube/videos/{video_id}/comments`](/api-reference/endpoint/youtube/video-comments) | GET | Top-level comments |
| [`/v1/youtube/videos/{video_id}/comments/{comment_id}/replies`](/api-reference/endpoint/youtube/video-comments) | GET | Replies to a comment |
| [`/v1/youtube/videos/{video_id}/transcript`](/api-reference/endpoint/youtube/video-transcript) | GET | Timed transcript (SRT / VTT / text) |
| [`/v1/youtube/videos/{video_id}/captions`](/api-reference/endpoint/youtube/video-transcript) | GET | Available caption tracks |
| [`/v1/youtube/videos/{video_id}/streams`](/api-reference/endpoint/youtube/get-video) | GET | Streaming formats (best-effort URLs) |
| [`/v1/youtube/videos/{video_id}/live_chat`](/api-reference/endpoint/youtube/get-video) | GET | Live chat / chat replay messages |
| [`/v1/youtube/shorts/{video_id}`](/api-reference/endpoint/youtube/short) | GET | Full Shorts detail |
| [`/v1/youtube/shorts/by_sound/{sound_id}`](/api-reference/endpoint/youtube/short) | GET | Shorts using a given sound |

### Channels

| Endpoint | Method | Description |
| - | - | - |
| [`/v1/youtube/channels/{channel_id}`](/api-reference/endpoint/youtube/channel) | GET | Full channel detail (accepts `UC…`, `@handle`, or custom URL) |
| [`/v1/youtube/channels/{channel_id}/videos`](/api-reference/endpoint/youtube/channel-videos) | GET | A channel's videos |
| [`/v1/youtube/channels/{channel_id}/shorts`](/api-reference/endpoint/youtube/channel-videos) | GET | A channel's Shorts |
| [`/v1/youtube/channels/{channel_id}/streams`](/api-reference/endpoint/youtube/channel-videos) | GET | A channel's live streams |
| [`/v1/youtube/channels/{channel_id}/playlists`](/api-reference/endpoint/youtube/channel-videos) | GET | A channel's playlists |
| [`/v1/youtube/channels/{channel_id}/community`](/api-reference/endpoint/youtube/channel-videos) | GET | A channel's community posts |
| [`/v1/youtube/channels/{channel_id}/about`](/api-reference/endpoint/youtube/channel) | GET | Lightweight channel about payload |
| [`/v1/youtube/channels/{channel_id}/subscriber_count`](/api-reference/endpoint/youtube/channel) | GET | Fast subscriber-count-only lookup |
| [`/v1/youtube/channels/{channel_id}/search`](/api-reference/endpoint/youtube/channel-videos) | GET | Search within a channel |
| [`/v1/youtube/channels/resolve`](/api-reference/endpoint/youtube/resolve-channel) | GET | Resolve a handle / URL to canonical ids |

### Playlists

| Endpoint | Method | Description |
| - | - | - |
| [`/v1/youtube/playlists/{playlist_id}`](/api-reference/endpoint/youtube/playlist) | GET | Full playlist detail + first item page |
| [`/v1/youtube/playlists/{playlist_id}/items`](/api-reference/endpoint/youtube/playlist-items) | GET | A page of playlist items |
| [`/v1/youtube/mixes/{mix_id}`](/api-reference/endpoint/youtube/playlist) | GET | An auto-generated mix |

### Community & Reference

| Endpoint | Method | Description |
| - | - | - |
| [`/v1/youtube/posts/{post_id}`](/api-reference/endpoint/youtube/community-post) | GET | A community post |
| [`/v1/youtube/posts/{post_id}/comments`](/api-reference/endpoint/youtube/community-post) | GET | Comments on a community post |
| [`/v1/youtube/oembed`](/api-reference/endpoint/youtube/resolve-channel) | GET | Public oEmbed metadata for a URL |
| [`/v1/youtube/categories`](/api-reference/endpoint/youtube/resolve-channel) | GET | Video category reference list |
| [`/v1/youtube/languages`](/api-reference/endpoint/youtube/resolve-channel) | GET | Supported UI languages (`hl`) |
| [`/v1/youtube/regions`](/api-reference/endpoint/youtube/resolve-channel) | GET | Supported content regions (`gl`) |
| [`/v1/youtube/markets`](/api-reference/endpoint/youtube/resolve-channel) | GET | Supported markets reference |

## Credit Costs

| Endpoint | Cost |
| - | - |
| Search | 5 credits |
| Trending / hashtag / home | 5 credits |
| Music search | 5 credits |
| Video detail | 10 credits |
| Batch videos | 10 credits per video |
| Related / comments / replies / live chat | 5 credits |
| Transcript | 5 credits |
| Streams | 15 credits |
| Captions | 2 credits |
| Short detail / shorts by sound | 5 credits |
| Channel detail | 5 credits |
| Channel videos / shorts / streams / playlists / community / search | 5 credits |
| Channel about / subscriber count / resolve | 2 credits |
| Playlist / playlist items / mix | 5 credits |
| Community post / post comments | 5 credits |
| Autocomplete / oEmbed | 1 credit |
| Categories / languages / regions / markets | 0 credits |
| Failed requests | 0 credits |

## Authentication

All requests require your API key in the `X-API-Key` header:

```bash theme={null}
curl "https://scrapebadger.com/v1/youtube/videos/dQw4w9WgXcQ" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Anti-Bot Handling

YouTube protects its data with IP-reputation scoring, TLS/HTTP-2 fingerprinting, bot-guard challenges, and PO-token requirements on media. ScrapeBadger clears these automatically using Chrome TLS impersonation on sessions matched to the target region. You never need to manage proxies, sessions, or tokens.

<Note>
  For accurate, localized results, requests are routed through proxies in the `gl` region. This is handled automatically. Some fields (such as `dislike_count` and direct media `url`s) are restricted by YouTube platform-wide and may be `null`.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Search YouTube" icon="magnifying-glass" href="/api-reference/endpoint/youtube/search">
    Full API reference for searching videos, channels, and playlists
  </Card>

  <Card title="Get Video Detail" icon="video" href="/api-reference/endpoint/youtube/get-video">
    Fetch full metadata for a single video
  </Card>
</CardGroup>

***

*ScrapeBadger is an independent tool and is not affiliated with, endorsed by, or sponsored by YouTube. "YouTube" is a trademark of Google LLC, used here only to describe the platform this scraper is designed to work with.*


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