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

# YouTube

> Long-form, Shorts, and the legal requirement of 'Made for Kids'.

YouTube handles both traditional long-form videos and Shorts (vertical video). The API comes with legal requirements you can't ignore.

## Supported Content Types

* **Videos:** Long-form content. 1 video, up to 4 hours. Max 5 GB.
* **Shorts:** Vertical/square video, max 3 minutes. YouTube auto-detects based on duration and aspect ratio.

## Quirks & Gotchas

### "Made for Kids" (COPPA)

This is not just a quirk, it's a **legal requirement**.

* You **must** flag content as `madeForKids: true` if it targets children.
* Failure to do so can result in penalties - real ones, from the FTC.
* We expose this field in the `data.YOUTUBE` object. Use it. Don't skip it. Don't "figure it out later".

### Shorts Detection

There is no special "upload as Short" button. YouTube decides for you based on the file:

* **Duration:** Under **3 minutes** (180 seconds).
* **Aspect Ratio:** Vertical (9:16) or Square (1:1). Technically 1:3 to 1:1.

If your video meets these criteria, it becomes a Short. If it doesn't, it's a regular video.

### YouTube Title is Required

Unlike most platforms where you just need text, YouTube treats `data.YOUTUBE.text` as the **video title**. If you leave it empty, YouTube can reject the upload.

### Media Limits

See [Platform Limits](/api-reference/limits#youtube) for the full breakdown.

### Text & Field Limits

| Field                | Limit                |
| :------------------- | :------------------- |
| `text` (video title) | Max 100 characters   |
| `description`        | Max 5,000 characters |

***

## Post Options

Send YouTube-specific options inside `data.YOUTUBE`.

| Field                     | Type       | Description                                                                       |
| :------------------------ | :--------- | :-------------------------------------------------------------------------------- |
| `type`                    | `enum`     | `VIDEO` or `SHORT`. Default: `SHORT`.                                             |
| `uploadIds`               | `string[]` | Required. One uploaded video.                                                     |
| `text`                    | `string`   | Video title. Max 100 characters.                                                  |
| `description`             | `string`   | Video description. Max 5,000 characters.                                          |
| `thumbnail`               | `string`   | Optional thumbnail image URL uploaded through bundle.social.                      |
| `privacy`                 | `enum`     | `PRIVATE`, `PUBLIC`, or `UNLISTED`. Default sent to YouTube is public if omitted. |
| `madeForKids`             | `boolean`  | Required by YouTube policy. Set `true` when the video is made for children.       |
| `containsSyntheticMedia`  | `boolean`  | Set `true` when the video contains AI-generated or synthetic content.             |
| `hasPaidProductPlacement` | `boolean`  | Set `true` when the video contains paid product placement.                        |

```json theme={null}
{
  "teamId": "team_123",
  "title": "YouTube launch video",
  "status": "SCHEDULED",
  "postDate": "2026-06-01T15:00:00.000Z",
  "socialAccountTypes": ["YOUTUBE"],
  "data": {
    "YOUTUBE": {
      "type": "VIDEO",
      "uploadIds": ["upload_video_123"],
      "text": "Product launch walkthrough",
      "description": "A full walkthrough of the new release.",
      "privacy": "PUBLIC",
      "madeForKids": false,
      "containsSyntheticMedia": false,
      "hasPaidProductPlacement": false
    }
  }
}
```

***

## Analytics

For general analytics concepts (refresh rates, data retention, what "Returns 0" means), see the [Analytics Overview](/api-reference/analytics).

YouTube analytics are all **Lifetime** values. There is no rolling window - everything is cumulative from day one.

### Profile (Channel) Analytics

**Period:** Lifetime.

| Metric              | Description         | Note                                              |
| :------------------ | :------------------ | :------------------------------------------------ |
| `impressions`       | Total channel views |                                                   |
| `impressionsUnique` | -                   | Same as impressions (YouTube doesn't distinguish) |
| `views`             | Total channel views | Same as impressions                               |
| `viewsUnique`       | -                   | Same as views                                     |
| `likes`             | -                   | Returns `0` (not available at channel level)      |
| `comments`          | Total comments      | Across all videos                                 |
| `postCount`         | Total videos        |                                                   |
| `followers`         | Subscribers         |                                                   |
| `following`         | -                   | Returns `0` (not applicable to channels)          |

### Post (Video) Analytics

**Period:** Lifetime.

| Metric              | Description | Note                                                       |
| :------------------ | :---------- | :--------------------------------------------------------- |
| `impressions`       | Video views |                                                            |
| `impressionsUnique` | -           | Same as impressions (YouTube doesn't distinguish)          |
| `views`             | Video views | Same as impressions                                        |
| `viewsUnique`       | -           | Same as views                                              |
| `likes`             | Likes       |                                                            |
| `dislikes`          | Dislikes    | Available via API even though YouTube hides them on the UI |
| `comments`          | Comments    |                                                            |
| `shares`            | -           | Returns `0` (not provided by YouTube API)                  |
| `saves`             | Favorites   |                                                            |

### Quirks

* YouTube doesn't distinguish between impressions and unique impressions at any level.
* Dislikes are available through the API (though YouTube no longer shows dislike counts publicly). Handy if you want to know the truth.
* Channel-level likes are not available. Post shares are not available. YouTube gives us a lot, but not everything.

### Raw Analytics - Demographics & Audience Data

YouTube raw analytics include demographics data when enabled for your organization. We query the YouTube Analytics API for each video and return age/gender breakdowns and country-level view counts.

#### Video-Level Raw Data

```json theme={null}
{
  "video": {
    "id": "dQw4w9WgXcQ",
    "snippet": {
      "title": "My Video",
      "publishedAt": "2026-01-15T10:00:00Z"
    },
    "statistics": {
      "viewCount": "125000",
      "likeCount": "8900",
      "commentCount": "342"
    }
  },
  "demographics": {
    "ageGender": {
      "columnHeaders": [
        { "name": "ageGroup", "columnType": "DIMENSION" },
        { "name": "gender", "columnType": "DIMENSION" },
        { "name": "viewerPercentage", "columnType": "METRIC" }
      ],
      "rows": [
        ["age18-24", "female", 12.3],
        ["age18-24", "male", 18.7],
        ["age25-34", "female", 14.1],
        ["age25-34", "male", 22.4],
        ["age35-44", "female", 8.2],
        ["age35-44", "male", 11.5]
      ]
    },
    "country": {
      "columnHeaders": [
        { "name": "country", "columnType": "DIMENSION" },
        { "name": "views", "columnType": "METRIC" }
      ],
      "rows": [
        ["US", 45200],
        ["GB", 12800],
        ["DE", 8900],
        ["BR", 7200]
      ]
    }
  }
}
```

<Note>
  **Empty demographics data is normal.** YouTube has undocumented thresholds for when demographics become available. Unlike Instagram (\~1,000 followers), nobody knows YouTube's minimum. If `demographics` comes back empty or null for your videos, it likely means the account or video hasn't hit the threshold yet. If you do see data, let us know your account stats - we're trying to figure out the threshold too.
</Note>

<Info>
  Raw YouTube data includes **viewer percentage by age group and gender** and **views by country** (sorted by view count, descending). This is useful for audience analysis and content strategy - especially if you're targeting specific demographics or regions.
</Info>