# YouTube API (ScrapeIO)

19 endpoints for public YouTube data. Same response format and field names as every other platform.

## Basics

- Base URL: `https://scrapeio.com`
- Auth: send your key in the `x-api-key` header. Get a key at https://scrapeio.com/login (100 free credits, no card).
- Every endpoint is a GET with query parameters and returns JSON:
  `{ "success": true, "cached": false, "credits_used": 1, "credits_remaining": 99, "data": { ... } }`
- Field names are the same on every platform (`handle`, `followers`, `plays`, `likes`, `comments`, `created_at`).
- Lists return `data.items`, `data.cursor` and `data.has_more`. Pass `cursor` back to get the next page.
- Each endpoint has one listed price. Cached repeats, failed calls, private and not-found answers cost 0.
- Limit: 300 requests a minute per key.

## Errors

| Status | Meaning | Charged |
| --- | --- | --- |
| 200 | Success | Yes, unless cached |
| 400 | A parameter is missing or wrong | No |
| 401 | The key is missing or invalid | No |
| 402 | Not enough credits | No |
| 403 | The account or post is private | No |
| 404 | Not found on the platform | No |
| 429 | More than 300 requests a minute | No |
| 502 | Every source is down; retry shortly | No |

### GET /v1/youtube/channel

YouTube channel: subscribers, total views, video count, description. Price: 1 credit. MCP tool: `youtube_channel`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | Channel @handle, channel URL, or UC… channel id. |

```bash
curl "https://scrapeio.com/v1/youtube/channel?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/channel-videos

A channel's uploads (videos and Shorts), newest first, with views, likes and comments. Price: 1 credit. MCP tool: `youtube_channel_videos`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | Channel @handle, channel URL, or UC… channel id. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/youtube/channel-videos?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/video

One YouTube video or Short by URL: views, likes, comments, duration, tags. Price: 1 credit. MCP tool: `youtube_video`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | YouTube video or Short URL. |

```bash
curl "https://scrapeio.com/v1/youtube/video?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/video/comments

Comments on a YouTube video. Price: 1 credit. MCP tool: `youtube_comments`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | YouTube video URL. |
| `order` | string (relevance, time) | no | Ranking. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/youtube/video/comments?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/search

Search YouTube videos with full stats. Price: 2 credits. MCP tool: `youtube_search`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Search text. |
| `sort_by` | string (relevance, date, viewCount, rating) | no | Ranking. |
| `published_after` | string | no | RFC 3339 time, e.g. 2026-01-01T00:00:00Z. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/youtube/search?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/video/download

Direct MP4 stream URLs for a video (360p with audio, plus every format). Price: 2 credits. MCP tool: `youtube_download`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | YouTube video URL. |

```bash
curl "https://scrapeio.com/v1/youtube/video/download?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/video/transcript

A YouTube video's captions as text, with timestamps. Price: 5 credits. MCP tool: `youtube_transcript`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | YouTube video or Short URL. |
| `language` | string | no | Preferred language code, e.g. en. |

```bash
curl "https://scrapeio.com/v1/youtube/video/transcript?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/playlist

A playlist's details and its videos, with views and likes. Price: 1 credit. MCP tool: `youtube_playlist`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `playlist_id` | string | yes | Playlist id or playlist URL. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/youtube/playlist?playlist_id=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/channel/playlists

A channel's public playlists. Price: 1 credit. MCP tool: `youtube_channel_playlists`.

Send one of: `handle`, `channelId`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | no | Channel handle, e.g. @MrBeast. |
| `channelId` | string | no | Channel id (UC...). Send this or handle. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/youtube/channel/playlists?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/channel/shorts

A channel's Shorts, newest first, with views and likes. Price: 1 credit. MCP tool: `youtube_channel_shorts`.

Send one of: `handle`, `channelId`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | no | Channel handle, e.g. @MrBeast. |
| `channelId` | string | no | Channel id (UC...). Send this or handle. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/youtube/channel/shorts?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/channel/lives

A channel's past and current live streams. Price: 1 credit. MCP tool: `youtube_channel_lives`.

Send one of: `handle`, `channelId`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | no | Channel handle, e.g. @MrBeast. |
| `channelId` | string | no | Channel id (UC...). Send this or handle. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/youtube/channel/lives?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/video/comment/replies

Replies to one YouTube comment. Price: 1 credit. MCP tool: `youtube_comment_replies`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `comment_id` | string | yes | Comment id from the comments endpoint. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/youtube/video/comment/replies?comment_id=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/search/typeahead

Search suggestions YouTube shows as you type. Price: 1 credit. MCP tool: `youtube_search_typeahead`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Partial search text. |

```bash
curl "https://scrapeio.com/v1/youtube/search/typeahead?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/channel/community-posts

A channel's community posts: text, images, polls, likes and comments. Price: 1 credit. MCP tool: `youtube_community_posts`.

Send one of: `handle`, `channelId`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | no | Channel handle, e.g. @MrBeast. |
| `channelId` | string | no | Channel id (UC...). Send this or handle. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |
| `continuationToken` | string | no | Same as cursor, under ScrapeCreators' name. |

```bash
curl "https://scrapeio.com/v1/youtube/channel/community-posts?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/community-post

One community post with its text, images and likes. Price: 1 credit. MCP tool: `youtube_community_post`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Community post URL. |

```bash
curl "https://scrapeio.com/v1/youtube/community-post?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/channel/search

Search inside one channel's videos. Price: 1 credit. MCP tool: `youtube_channel_search`.

Send one of: `handle`, `channelId`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | no | Channel handle, e.g. @MrBeast. |
| `channelId` | string | no | Channel id (UC...). Send this or handle. |
| `query` | string | yes | Search text. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |
| `continuationToken` | string | no | Same as cursor, under ScrapeCreators' name. |

```bash
curl "https://scrapeio.com/v1/youtube/channel/search?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/search/hashtag

Videos under a YouTube hashtag, with views and length. Price: 1 credit. MCP tool: `youtube_search_hashtag`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `hashtag` | string | yes | Hashtag, with or without #. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |
| `continuationToken` | string | no | Same as cursor, under ScrapeCreators' name. |

```bash
curl "https://scrapeio.com/v1/youtube/search/hashtag?hashtag=travel" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/shorts/trending

Trending Shorts Price: 5 credits. MCP tool: `youtube_shorts_trending`.

```bash
curl "https://scrapeio.com/v1/youtube/shorts/trending" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/youtube/video/sponsors

Video Sponsors Price: 5 credits. MCP tool: `youtube_video_sponsors`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | YouTube video or short URL |
| `language` | string | no | 2 letter language code used for transcript lookup, ie 'en', 'es', 'fr' etc. |

```bash
curl "https://scrapeio.com/v1/youtube/video/sponsors?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```