> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/youtube.md).

# Youtube

YouTube: channels, videos, shorts, live streams, comments, search, trending, and hashtags. All endpoints are read-only `GET` requests and return public YouTube data — no channel or video of your own is required.

**Base URL:** `https://dashboard.pullbay.com/api`

## Endpoints

| Endpoint                                 | Description                                       | Pagination        |
| ---------------------------------------- | ------------------------------------------------- | ----------------- |
| `GET /youtube/channel`                   | Get a single channel by ID, handle, or URL        | —                 |
| `GET /youtube/channel/{id}/videos`       | Get videos uploaded by a channel                  | Cursor / maxItems |
| `GET /youtube/channel/{id}/shorts`       | Get shorts uploaded by a channel                  | Cursor / maxItems |
| `GET /youtube/channel/{id}/live-streams` | Get live streams (current and past) for a channel | Cursor / maxItems |
| `GET /youtube/video`                     | Get a single video's full metadata                | —                 |
| `GET /youtube/shorts/{id}`               | Get a single short's full metadata                | —                 |
| `GET /youtube/comments`                  | Get top-level comments on a video                 | Cursor / maxItems |
| `GET /youtube/search`                    | Search videos, channels, or playlists             | Cursor / maxItems |
| `GET /youtube/hashtag`                   | Get videos tagged with a hashtag                  | Cursor / maxItems |
| `GET /youtube/trending`                  | Get currently trending videos                     | —                 |

***

### Get Channel

Returns channel details. Provide exactly one of `id`, `handle`, or `channelUrl`.

**Request**

```bash
GET /youtube/channel
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter    | Type   | Required                          | Description                                                    |
| ------------ | ------ | --------------------------------- | -------------------------------------------------------------- |
| `id`         | string | One of `id`/`handle`/`channelUrl` | Channel ID, 1–100 characters (e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`) |
| `handle`     | string | One of `id`/`handle`/`channelUrl` | Channel handle, 1–100 characters (e.g. `@MrBeast`)             |
| `channelUrl` | string | One of `id`/`handle`/`channelUrl` | Full URL to the channel, 10–1000 characters                    |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/channel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d handle=@MrBeast
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "channel",
      "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
      "name": "MrBeast",
      "handle": "@MrBeast",
      "url": "http://www.youtube.com/@MrBeast",
      "description": "SUBSCRIBE FOR A COOKIE!",
      "thumbnails": "https://yt3.googleusercontent.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE",
      "isFamilySafe": true,
      "subscriberCount": "421M subscribers",
      "availableCountries": ["US", "GB", "CA"],
      "tags": ["mrbeast", "beast"],
      "joinedAt": "Joined Feb 20, 2012",
      "viewCount": "87,234,567,890 views",
      "videoCount": 837
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

### Get Channel Videos

Returns videos uploaded by the channel. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```bash
GET /youtube/channel/{id}/videos
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                                           |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `id`       | string  | Yes      | Channel ID, 1–100 characters — passed in the URL path                                 |
| `cursor`   | string  | No       | Opaque pagination cursor from a previous response. Mutually exclusive with `maxItems` |
| `maxItems` | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                   |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/channel/UCX6OQ3DkcsbYNE6H8uQQuVA/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d maxItems=25
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "video",
      "id": "EerdGm-ehJQ",
      "url": "https://www.youtube.com/watch?v=EerdGm-ehJQ",
      "title": "JavaScript Tutorial Full Course - Beginner to Pro",
      "description": "Get a certificate for this course",
      "thumbnails": [
        { "url": "https://i.ytimg.com/vi/EerdGm-ehJQ/hqdefault.jpg", "width": 480, "height": 360 }
      ],
      "richThumbnail": [],
      "channel": {
        "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "name": "MrBeast",
        "handle": "@MrBeast",
        "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
        "subscriberCount": "421M subscribers",
        "badges": [],
        "thumbnails": []
      },
      "publishDate": "1 year ago",
      "views": "8531468",
      "duration": "22:15:57"
    }
  ],
  "pagination": { "page": null, "hasNextPage": true, "cursor": "CAUQAA", "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of videos returned, not the number of requests.

***

### Get Channel Shorts

Returns shorts uploaded by the channel. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```bash
GET /youtube/channel/{id}/shorts
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                                           |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `id`       | string  | Yes      | Channel ID, 1–100 characters — passed in the URL path                                 |
| `cursor`   | string  | No       | Opaque pagination cursor from a previous response. Mutually exclusive with `maxItems` |
| `maxItems` | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                   |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/channel/UCX6OQ3DkcsbYNE6H8uQQuVA/shorts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d maxItems=25
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "video",
      "id": "kJQP7kiw5Fk",
      "url": "https://www.youtube.com/watch?v=kJQP7kiw5Fk",
      "title": "I Gave My 1,000th Subscriber A Island",
      "description": "Shorts edit of the full video",
      "thumbnails": [
        { "url": "https://i.ytimg.com/vi/kJQP7kiw5Fk/hqdefault.jpg", "width": 480, "height": 360 }
      ],
      "richThumbnail": [],
      "channel": {
        "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "name": "MrBeast",
        "handle": "@MrBeast",
        "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
        "subscriberCount": "421M subscribers",
        "badges": [],
        "thumbnails": []
      },
      "publishDate": "3 weeks ago",
      "views": "42531468",
      "duration": "0:58"
    }
  ],
  "pagination": { "page": null, "hasNextPage": true, "cursor": "CAUQAA", "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of shorts returned, not the number of requests.

***

### Get Channel Live Streams

Returns live streams (current and past) for the channel. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```bash
GET /youtube/channel/{id}/live-streams
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                                           |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `id`       | string  | Yes      | Channel ID, 1–100 characters — passed in the URL path                                 |
| `cursor`   | string  | No       | Opaque pagination cursor from a previous response. Mutually exclusive with `maxItems` |
| `maxItems` | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                   |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/channel/UCX6OQ3DkcsbYNE6H8uQQuVA/live-streams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d maxItems=25
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "video",
      "id": "5qap5aO4i9A",
      "url": "https://www.youtube.com/watch?v=5qap5aO4i9A",
      "title": "lofi hip hop radio - beats to relax/study to",
      "description": "24/7 livestream",
      "thumbnails": [
        { "url": "https://i.ytimg.com/vi/5qap5aO4i9A/hqdefault.jpg", "width": 480, "height": 360 }
      ],
      "richThumbnail": [],
      "channel": {
        "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "name": "MrBeast",
        "handle": "@MrBeast",
        "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
        "subscriberCount": "421M subscribers",
        "badges": [],
        "thumbnails": []
      },
      "publishDate": "Streamed live",
      "views": "9823145",
      "duration": "LIVE"
    }
  ],
  "pagination": { "page": null, "hasNextPage": true, "cursor": "CAUQAA", "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of streams returned, not the number of requests.

***

### Get Video

Returns full metadata for a single video by its 11-character video `id`.

**Request**

```bash
GET /youtube/video
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                                 |
| --------- | ------ | -------- | ----------------------------------------------------------- |
| `id`      | string | Yes      | 11-character video ID, 5–20 characters (e.g. `dQw4w9WgXcQ`) |
| `type`    | string | No       | `video` or `shorts` — hints the lookup at the content type  |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id=dQw4w9WgXcQ \
  -d type=video
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "video",
      "id": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
      "status": "OK",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "description": "The official video for \"Never Gonna Give You Up\" by Rick Astley.",
      "duration": 213,
      "views": 1766758607,
      "likes": 18978439,
      "comments": 2400000,
      "channel": {
        "id": "UCuAXFkgsw1L7xaCfnd5JJOw",
        "name": "Rick Astley",
        "handle": "@RickAstleyYT",
        "url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
        "subscriberCount": "4.49M subscribers",
        "badges": ["Official Artist Channel"],
        "thumbnails": []
      },
      "keywords": ["rick astley", "Never Gonna Give You Up"],
      "superTitle": "#RickAstley #NeverGonnaGiveYouUp #OfficialMusicVideo",
      "category": "Music",
      "isRatingsAllowed": true,
      "isLive": false,
      "isFamilySafe": true,
      "isPrivate": false,
      "isExclusive": false,
      "thumbnails": [
        { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "width": 480, "height": 360 }
      ]
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

### Get Short

Returns full metadata for a single short by its video `id`.

**Request**

```bash
GET /youtube/shorts/{id}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                                     |
| --------- | ------ | -------- | --------------------------------------------------------------- |
| `id`      | string | Yes      | 11-character video ID, 5–20 characters — passed in the URL path |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/shorts/kJQP7kiw5Fk" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "video",
      "id": "kJQP7kiw5Fk",
      "title": "I Gave My 1,000th Subscriber A Island",
      "status": "OK",
      "url": "https://www.youtube.com/watch?v=kJQP7kiw5Fk",
      "description": "Shorts edit of the full video",
      "duration": 58,
      "views": 42531468,
      "likes": 3198452,
      "comments": 18230,
      "channel": {
        "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "name": "MrBeast",
        "handle": "@MrBeast",
        "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
        "subscriberCount": "421M subscribers",
        "badges": [],
        "thumbnails": []
      },
      "keywords": ["mrbeast", "shorts", "giveaway"],
      "superTitle": "#MrBeast #Shorts",
      "category": "Entertainment",
      "isRatingsAllowed": true,
      "isLive": false,
      "isFamilySafe": true,
      "isPrivate": false,
      "isExclusive": false,
      "thumbnails": [
        { "url": "https://i.ytimg.com/vi/kJQP7kiw5Fk/hqdefault.jpg", "width": 480, "height": 360 }
      ]
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

### Get Comments

Returns top-level comments for a video. `sort` is `top` (default) or `latest`. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```bash
GET /youtube/comments
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                                           |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `id`       | string  | Yes      | 11-character video ID, 5–20 characters                                                |
| `sort`     | string  | No       | `top` (default) or `latest`                                                           |
| `cursor`   | string  | No       | Opaque pagination cursor from a previous response. Mutually exclusive with `maxItems` |
| `maxItems` | integer | No       | One-shot bulk pull, 1–500 results. Mutually exclusive with `cursor`                   |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id=dQw4w9WgXcQ \
  -d sort=top \
  -d maxItems=50
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "comment",
      "id": "UgwJsXlCbEu8-5nIK3h4AaABAg",
      "text": "Check out the latest Space Souvenirs Drop on the kurzgesagt shop",
      "likeCount": "1.8K",
      "replyCount": "59",
      "publishedTime": "1 month ago",
      "author": {
        "id": "UCsXVk37bltHxD1rDPwtNM8Q",
        "name": "@kurzgesagt",
        "thumbnails": "https://yt3.ggpht.com/ytc/AIdro_n1Ribd7LwdP_qKtqWL3ZDfIgv9M1d6g78VwpHGXVR2Ir4=s88-c-k-c0x00ffffff-no-rj"
      }
    }
  ],
  "pagination": { "page": null, "hasNextPage": true, "cursor": "Eg0SC2RRdzR3OVdnWGNRGAYyJSIRIgtkUXc0dzlXZ1hjURABGAA", "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of comments returned, not the number of requests.

***

### Search YouTube

Search YouTube. `mode` selects what to search for (`video`, `channel`, or `playlist`). When `mode=video`, results match the `YoutubeVideo` shape; other modes return shape variants. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```bash
GET /youtube/search
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter    | Type    | Required | Description                                                                                                                       |
| ------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `query`      | string  | Yes      | Search query, 1–100 characters                                                                                                    |
| `mode`       | string  | Yes      | `video`, `channel`, or `playlist`                                                                                                 |
| `sortBy`     | string  | No       | `relevance`, `rating`, `upload_date`, or `view_count`                                                                             |
| `lang`       | string  | No       | Language code, 2–5 characters                                                                                                     |
| `geo`        | string  | No       | Region code, 2–5 characters                                                                                                       |
| `duration`   | string  | No       | `short`, `medium`, or `long`                                                                                                      |
| `features`   | string  | No       | One feature filter — `360`, `hd`, `subtitles`, `creative_commons`, `3d`, `live`, `purchased`, `4k`, `location`, `hdr`, or `vr180` |
| `uploadDate` | string  | No       | `hour`, `today`, `week`, `month`, or `year`                                                                                       |
| `cursor`     | string  | No       | Opaque pagination cursor from a previous response. Mutually exclusive with `maxItems`                                             |
| `maxItems`   | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                                                               |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d query="javascript tutorial" \
  -d mode=video \
  -d sortBy=relevance \
  -d duration=long
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "video",
      "id": "EerdGm-ehJQ",
      "url": "https://www.youtube.com/watch?v=EerdGm-ehJQ",
      "title": "JavaScript Tutorial Full Course - Beginner to Pro",
      "description": "Get a certificate for this course",
      "thumbnails": [
        { "url": "https://i.ytimg.com/vi/EerdGm-ehJQ/hqdefault.jpg", "width": 480, "height": 360 }
      ],
      "richThumbnail": [],
      "channel": {
        "id": "UCW5YeuERMmlnqo4oq8vwUpg",
        "name": "freeCodeCamp.org",
        "handle": "@freecodecamp",
        "url": "https://www.youtube.com/channel/UCW5YeuERMmlnqo4oq8vwUpg",
        "subscriberCount": "10.4M subscribers",
        "badges": [],
        "thumbnails": []
      },
      "publishDate": "1 year ago",
      "views": "8531468",
      "duration": "22:15:57"
    }
  ],
  "pagination": { "page": null, "hasNextPage": true, "cursor": "CAUQAA", "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Using `maxItems` to pull more results in one call costs proportionally more than a single page.

***

### Get Hashtag

Returns videos tagged with `tag`. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```bash
GET /youtube/hashtag
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                                           |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `tag`      | string  | Yes      | Hashtag to look up, 1–100 characters, without the `#` (e.g. `shorts`)                 |
| `cursor`   | string  | No       | Opaque pagination cursor from a previous response. Mutually exclusive with `maxItems` |
| `maxItems` | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                   |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/hashtag" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d tag=shorts \
  -d maxItems=25
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "video",
      "id": "kJQP7kiw5Fk",
      "url": "https://www.youtube.com/watch?v=kJQP7kiw5Fk",
      "title": "I Gave My 1,000th Subscriber A Island #shorts",
      "description": "Shorts edit of the full video",
      "thumbnails": [
        { "url": "https://i.ytimg.com/vi/kJQP7kiw5Fk/hqdefault.jpg", "width": 480, "height": 360 }
      ],
      "richThumbnail": [],
      "channel": {
        "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "name": "MrBeast",
        "handle": "@MrBeast",
        "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
        "subscriberCount": "421M subscribers",
        "badges": [],
        "thumbnails": []
      },
      "publishDate": "3 weeks ago",
      "views": "42531468",
      "duration": "0:58"
    }
  ],
  "pagination": { "page": null, "hasNextPage": true, "cursor": "CAUQAA", "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of videos returned, not the number of requests.

***

### Get Trending

Returns currently trending videos. Use `geo` to target a country (e.g. `US`, `GB`).

**Request**

```bash
GET /youtube/trending
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                   |
| --------- | ------ | -------- | --------------------------------------------- |
| `geo`     | string | No       | Region code, 2–5 characters (e.g. `US`, `GB`) |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/youtube/trending" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d geo=US
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "video",
      "id": "5qap5aO4i9A",
      "url": "https://www.youtube.com/watch?v=5qap5aO4i9A",
      "title": "lofi hip hop radio - beats to relax/study to",
      "description": "24/7 livestream",
      "thumbnails": [
        { "url": "https://i.ytimg.com/vi/5qap5aO4i9A/hqdefault.jpg", "width": 480, "height": 360 }
      ],
      "richThumbnail": [],
      "channel": {
        "id": "UCSJ4gkVC6NrvII8umztf0Ow",
        "name": "Lofi Girl",
        "handle": "@LofiGirl",
        "url": "https://www.youtube.com/channel/UCSJ4gkVC6NrvII8umztf0Ow",
        "subscriberCount": "13.7M subscribers",
        "badges": [],
        "thumbnails": []
      },
      "publishDate": "Streamed live",
      "views": "9823145",
      "duration": "LIVE"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

## Object schemas

### Channel object

| Field                | Type    | Description                                                   |
| -------------------- | ------- | ------------------------------------------------------------- |
| `type`               | string  | Always `channel`                                              |
| `id`                 | string  | Channel ID                                                    |
| `name`               | string  | Channel display name                                          |
| `handle`             | string  | Channel handle (e.g. `@MrBeast`)                              |
| `url`                | string  | Channel URL                                                   |
| `description`        | string  | Channel "About" description                                   |
| `thumbnails`         | string  | Channel avatar image URL                                      |
| `isFamilySafe`       | boolean | Whether the channel is marked family-safe                     |
| `subscriberCount`    | string  | Subscriber count, formatted (e.g. `421M subscribers`)         |
| `availableCountries` | array   | Country codes where the channel is available                  |
| `tags`               | array   | Channel keyword tags                                          |
| `joinedAt`           | string  | Channel creation date, formatted (e.g. `Joined Feb 20, 2012`) |
| `viewCount`          | string  | All-time view count, formatted                                |
| `videoCount`         | integer | Total number of uploaded videos                               |

### Channel reference object

Lightweight channel reference embedded in video and comment results.

| Field             | Type                                    | Description                                     |
| ----------------- | --------------------------------------- | ----------------------------------------------- |
| `id`              | string                                  | Channel ID                                      |
| `name`            | string                                  | Channel display name                            |
| `handle`          | string                                  | Channel handle                                  |
| `url`             | string                                  | Channel URL                                     |
| `subscriberCount` | string                                  | Subscriber count, formatted                     |
| `badges`          | array                                   | Channel badges (e.g. `Official Artist Channel`) |
| `thumbnails`      | array of [Thumbnail](#thumbnail-object) | Channel avatar thumbnails at different sizes    |

### Video object

Video result returned by the channel videos/shorts/live-streams, search, hashtag, and trending endpoints.

| Field           | Type                                           | Description                                                            |
| --------------- | ---------------------------------------------- | ---------------------------------------------------------------------- |
| `type`          | string                                         | Always `video`                                                         |
| `id`            | string                                         | 11-character video ID                                                  |
| `url`           | string                                         | Video watch URL                                                        |
| `title`         | string                                         | Video title                                                            |
| `description`   | string                                         | Video description snippet                                              |
| `thumbnails`    | array of [Thumbnail](#thumbnail-object)        | Thumbnail images at different sizes                                    |
| `richThumbnail` | array of [Thumbnail](#thumbnail-object)        | Animated/rich preview thumbnails, if available                         |
| `channel`       | [Channel reference](#channel-reference-object) | Uploading channel                                                      |
| `publishDate`   | string                                         | Relative publish date (e.g. `1 year ago`)                              |
| `views`         | string                                         | View count as a string                                                 |
| `duration`      | string                                         | Video duration, formatted (e.g. `22:15:57`); `LIVE` for active streams |

### Video detail object

Full video metadata returned by the get video and get short endpoints.

| Field              | Type                                           | Description                                    |
| ------------------ | ---------------------------------------------- | ---------------------------------------------- |
| `type`             | string                                         | Always `video`                                 |
| `id`               | string                                         | 11-character video ID                          |
| `title`            | string                                         | Video title                                    |
| `status`           | string                                         | Lookup status (e.g. `OK`)                      |
| `url`              | string                                         | Video watch URL                                |
| `description`      | string                                         | Full video description                         |
| `duration`         | integer                                        | Length in seconds                              |
| `views`            | integer                                        | View count                                     |
| `likes`            | integer                                        | Like count                                     |
| `comments`         | integer                                        | Total comment count                            |
| `channel`          | [Channel reference](#channel-reference-object) | Uploading channel                              |
| `keywords`         | array                                          | Video tags/keywords                            |
| `superTitle`       | string                                         | Hashtag/super-title line shown above the title |
| `category`         | string                                         | YouTube content category (e.g. `Music`)        |
| `isRatingsAllowed` | boolean                                        | Whether likes/dislikes are enabled             |
| `isLive`           | boolean                                        | Whether the video is a live broadcast          |
| `isFamilySafe`     | boolean                                        | Whether the video is marked family-safe        |
| `isPrivate`        | boolean                                        | Whether the video is private                   |
| `isExclusive`      | boolean                                        | Whether the video is exclusive/members-only    |
| `thumbnails`       | array of [Thumbnail](#thumbnail-object)        | Thumbnail images at different sizes            |

### Comment object

| Field           | Type                                     | Description                                |
| --------------- | ---------------------------------------- | ------------------------------------------ |
| `type`          | string                                   | Always `comment`                           |
| `id`            | string                                   | Comment ID                                 |
| `text`          | string                                   | Comment body text                          |
| `likeCount`     | string                                   | Like count, formatted (e.g. `1.8K`)        |
| `replyCount`    | string                                   | Reply count, formatted                     |
| `publishedTime` | string                                   | Relative publish time (e.g. `1 month ago`) |
| `author`        | [Comment author](#comment-author-object) | Commenter                                  |

### Comment author object

| Field        | Type   | Description                  |
| ------------ | ------ | ---------------------------- |
| `id`         | string | Author's channel ID          |
| `name`       | string | Author's display name/handle |
| `thumbnails` | string | Author's avatar image URL    |

### Thumbnail object

| Field    | Type    | Description            |
| -------- | ------- | ---------------------- |
| `url`    | string  | Thumbnail image URL    |
| `width`  | integer | Image width in pixels  |
| `height` | integer | Image height in pixels |

***

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                                                                                          |
| ------ | ---------------------------------------------------------------------------------------------------------------- |
| `400`  | Bad request — missing/invalid parameters, or more than one of `id`/`handle`/`channelUrl` supplied to Get Channel |
| `402`  | Insufficient credits                                                                                             |
| `404`  | Channel, video, short, or comment thread not found                                                               |

## Channel, Video, and Short IDs

* **Channel ID**: the `UC...` string in a channel URL, e.g. `https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA` → `UCX6OQ3DkcsbYNE6H8uQQuVA`. Pass it as the `id` path/query parameter depending on the endpoint.
* **Handle**: the `@name` shown on a channel's page, e.g. `https://www.youtube.com/@MrBeast` → `@MrBeast`.
* **Video/Short ID**: the 11-character `v=` value in a watch URL or the trailing path segment of a shorts URL, e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ` → `dQw4w9WgXcQ`. The same ID format is used for both regular videos and shorts — use `/youtube/video` or `/youtube/shorts/{id}` depending on which you're looking up.

## Pagination Notes

* `GET /youtube/channel`, `GET /youtube/video`, `GET /youtube/shorts/{id}`, and `GET /youtube/trending` are single-object or fixed-size lookups and have no pagination parameters.
* All list endpoints (channel videos, channel shorts, channel live streams, comments, search, hashtag) use cursor-based pagination: pass the `cursor` value from `pagination.cursor` in a response to fetch the next page, or use `maxItems` instead to pull a bulk batch in one call. The two are mutually exclusive.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pullbay.com/api-reference/endpoints/youtube.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.