# YouTube

Canonical: https://monsterapi.co/docs/youtube

Read public YouTube data at `https://api.monsterapi.co/youtube/api` with a MonsterAPI bearer key.
Anonymous access can be restricted for age-limited or private content.

## First request

Set `MONSTERAPI_KEY` to your MonsterAPI key. Then request video details:

```bash
curl -sS 'https://api.monsterapi.co/youtube/api/video/dQw4w9WgXcQ' \
  -H "Authorization: Bearer ${MONSTERAPI_KEY}"
```

The response contains video information, related records, and a `comments_cursor` when comments are available.
The [API reference](https://monsterapi.co/docs/api) describes every operation, parameter, and response field.

## Choose an operation

| Information                         | Operation                                                               |
| ----------------------------------- | ----------------------------------------------------------------------- |
| Video details and comments cursor   | [GET /video/\{id\}](https://monsterapi.co/docs/api/youtube-video#video-details)                   |
| Video metadata and playback formats | [GET /video/\{id\}/player](https://monsterapi.co/docs/api/youtube-video#video-player-information) |
| Channel details                     | [GET /channel/\{id\}](https://monsterapi.co/docs/api/youtube-channel#channel-details)             |
| Channel videos                      | [GET /channel/\{id\}/videos](https://monsterapi.co/docs/api/youtube-channel#channel-videos)       |
| Channel Shorts                      | [GET /channel/\{id\}/shorts](https://monsterapi.co/docs/api/youtube-channel#channel-shorts)       |
| Channel broadcasts and recordings   | [GET /channel/\{id\}/streams](https://monsterapi.co/docs/api/youtube-channel#channel-streams)     |
| Channel playlists                   | [GET /channel/\{id\}/playlists](https://monsterapi.co/docs/api/youtube-channel#channel-playlists) |
| Channel information and links       | [GET /channel/\{id\}/about](https://monsterapi.co/docs/api/youtube-channel#channel-information)   |
| Search results                      | [GET /search](https://monsterapi.co/docs/api/youtube-search#search-results)                       |
| Search suggestions                  | [GET /search/suggestions](https://monsterapi.co/docs/api/youtube-search#search-suggestions)       |
| Playlist information and videos     | [GET /playlist/\{id\}](https://monsterapi.co/docs/api/youtube-playlist#playlist-videos)           |
| Video comments and replies          | [GET /comments](https://monsterapi.co/docs/api/youtube-comments#video-comments)                   |
| Identifiers for a YouTube URL       | [GET /resolve](https://monsterapi.co/docs/api/youtube-resolve#youtube-url-identifiers)            |

## Read response values and identifiers

Each response contains resources for the requested operation. The old `data` property is removed.
Text fields such as `title` and `text` are plain strings.
Unavailable optional fields can be absent or `null`. Keep identifiers as strings, exactly as returned.

| Operation                             | Response branches                                   |
| ------------------------------------- | --------------------------------------------------- |
| `/channel/{id}`                       | `channel`, `items`, `next_cursor`, `about_cursor`   |
| `/video/{id}`                         | `video`, `items`, `chapters`, `comments_cursor`     |
| `/video/{id}/player`                  | `video`, `playback`, `live_broadcast`               |
| Channel lists, `/search`, `/comments` | `items`, `next_cursor`, and `channel` when supplied |
| `/playlist/{id}`                      | `playlist`, `items`, `next_cursor`                  |
| `/channel/{id}/about`                 | `about`                                             |
| `/resolve`                            | `resolved`                                          |
| `/search/suggestions`                 | `suggestions`                                       |

Read `channel.id`, `items[].title`, or `items[].text` directly. Do not read text from a nested `content` or `runs` object.
Items retain useful authors, badges, images, and `metadata_texts`.
Title and comment destinations appear in `title_links`, `published_time_links`, and `text_links`.
Mentions appear in `title_mentions` and `text_mentions`. Keep their supplied offsets unchanged.

An item’s `type` identifies a business record:
`video`, `short`, `channel`, `playlist`, `comment`, `course`, `album`, `advertisement`, or `post`.

The following code uses responses from `/channel/{id}` and `/comments`:

```javascript
const channelId = channelResponse.channel?.id
const firstTitle = channelResponse.items?.[0]?.title
const firstCommentText = commentsResponse.items?.[0]?.text
```

`firstTitle` and `firstCommentText` contain plain text when available.

A video ID contains 11 letters, digits, underscores, or hyphens.
Use `video.id` for `/video/{id}` and `/video/{id}/player`.
A channel ID begins with `UC`, followed by 22 letters, digits, underscores, or hyphens.
Use `video.channel_id` from `/video/{id}/player` for `/channel/{id}` and `/channel/{id}/videos`.

For a playlist ID, use the `list` parameter of a YouTube URL.
Search results also supply playlist IDs in `items[].id` for records with `type: playlist`.

## Resolve a YouTube URL

Pass the complete URL as the `url` query value to [GET /resolve](https://monsterapi.co/docs/api/youtube-resolve#youtube-url-identifiers):

```bash
curl -sS --get 'https://api.monsterapi.co/youtube/api/resolve' \
  -H "Authorization: Bearer ${MONSTERAPI_KEY}" \
  --data-urlencode 'url=https://www.youtube.com/@YouTube'
```

The `resolved` object can include `channel_id`, `video_id`, `playlist_id`, and `url` when available.
Use the returned identifier for a separate channel, video, or playlist request.
The response contains destination identifiers rather than the destination’s complete information.
The reference describes the accepted HTTPS hosts, paths, and query parameters.

## Read channel information

Request `/channel/{id}` first. Take the top-level `about_cursor` from that response.
Pass it unchanged as `cursor` to `/channel/{id}/about` with the same channel ID.
Both the channel ID and cursor are required. If `about_cursor` is `null`, no information cursor is available.

Set `CHANNEL_ID` and `ABOUT_CURSOR` to those response values:

```bash
curl -sS --get "https://api.monsterapi.co/youtube/api/channel/${CHANNEL_ID}/about" \
  -H "Authorization: Bearer ${MONSTERAPI_KEY}" \
  --data-urlencode "cursor=${ABOUT_CURSOR}"
```

The `about` object contains available descriptions, country, view and video-count text, join-date text, and external links.
The `channel` object can also include keyword text, an RSS URL, owner URLs, country codes, family suitability, and banner images.
Published count text retains its original precision. External links keep their titles, display text, destinations, and images separate.

## Read video and result details

Video details can include `chapters` in returned order.
Each chapter includes its complete `title`, `start_time_millis` in milliseconds, and all available `thumbnails`.
Unavailable chapters are `null`.

The `video` object from `/video/{id}/player` can include publication and upload dates, category, keywords, and available countries.
Dates retain the published timezone offset. Optional flags describe family suitability, unlisted status, and Shorts eligibility.
`likes_count` contains an exact integer when available. Owner, canonical, and embedding information also remain available when supplied.

Playback availability and formats appear in `playback`. Broadcast timing appears in `live_broadcast` when available.
These resource branches remain separate from `video` metadata.

Result records can include author information, channel identifiers, duration text, publication text, view-count text, snippets, badges, and metadata.
Rounded view and subscriber phrases remain text. Relative publication text does not establish an exact calendar date.
Text values, business links, mentions, and image variants remain available. Missing values do not establish a zero count or a `false` flag.

## Search and filter

Search uses the required `query` parameter. Search text accepts 1 to 512 characters without control characters.
URL-encode the complete query value:

```bash
curl -sS --get 'https://api.monsterapi.co/youtube/api/search' \
  -H "Authorization: Bearer ${MONSTERAPI_KEY}" \
  --data-urlencode 'query=rust programming'
```

Use one optional `filter` value per request:

| Value        | Selection  |
| ------------ | ---------- |
| `videos`     | Videos     |
| `channels`   | Channels   |
| `playlists`  | Playlists  |
| `shorts`     | Shorts     |
| `this_week`  | This week  |
| `popularity` | Popularity |

Omit `filter` for unfiltered results. Multiple filters cannot be combined in one request.
For continuation, keep both `query` and `filter` unchanged. If either value changes, request a new first page.

[GET /search/suggestions](https://monsterapi.co/docs/api/youtube-search#search-suggestions) uses the same required `query` parameter.
The response includes `suggestions` in returned order.
Each suggestion can include a plain `text` string, numeric `type`, and numeric `subtypes`.
Use a suggestion’s non-null `text` as `query` for a separate search request.

## Continue a list

Each list response contains one page. Pass `next_cursor` unchanged as `cursor` to the same GET path with the same parameters.
Keep the same channel ID, playlist ID, search query, and search filter. When `next_cursor` is `null`, stop.

Channel list cursors belong to their original list path. Do not move a cursor between videos, Shorts, streams, or playlists.

Records can repeat within or across pages. Playlist search results can repeat identifiers across pages.
Keep the returned order. If the application needs one copy of each record, remove duplicates by the returned identifier.

For the first comments page, take `comments_cursor` from `/video/{id}`.
Pass this value unchanged as `cursor` to `/comments`. If `comments_cursor` is `null`, no comments cursor is available.
For an available comments cursor, set `COMMENTS_CURSOR` to that value:

```bash
curl -sS --get 'https://api.monsterapi.co/youtube/api/comments' \
  -H "Authorization: Bearer ${MONSTERAPI_KEY}" \
  --data-urlencode "cursor=${COMMENTS_CURSOR}"
```

For replies, pass `items[].replies_cursor` from the selected comment unchanged as `cursor` to `/comments`.
Then continue either comments or replies with `next_cursor` from `/comments`.
A `null` reply cursor means that no reply page is available for that comment.

## Handle errors and credits

Check the current operation price in the [API reference](https://monsterapi.co/docs/api). Each page is a separate request.
Endpoint responses with `2xx` or `4xx` are charged. Responses with `5xx` are refunded.
Gateway rejections are not charged.

A `5xx` response does not establish that a list is empty or complete.
An empty selected list or filtered search without a continuation returns `404` `not_found`.
This response does not prove that the channel is absent.
Video metadata can remain available when playback is unavailable.

Use the response status and error code from the [API reference](https://monsterapi.co/docs/api).
See [Authentication](https://monsterapi.co/docs/authentication), [Errors](https://monsterapi.co/docs/errors), and [Pricing](https://monsterapi.co/docs/pricing) for the shared rules.

## Public examples

Use the [API reference](https://monsterapi.co/docs/api) for ready-made public inputs and response examples.
Read [Examples](https://monsterapi.co/docs/examples) for provenance, preparation costs, task recipes, and pagination stop rules.