youtube-channels

    required_for: all API requests
metadata: {"openclaw":{"emoji":"📡","requires":{"env":["TRANSCRIPT_API_KEY"]},"primaryEnv":"TRANSCRIPT_API_KEY","homepage":"https://transcriptapi.com"},"hermes":{"tags":["youtube","channels","video","uploads","creator","browsing"],"category":"media"}}
---

# YouTube Channels

YouTube channel tools via [TranscriptAPI.com](https://transcriptapi.com).

## Setup

If `$TRANSCRIPT_API_KEY` is not set, read [references/auth-setup.md](references/auth-setup.md) and follow the instructions there to get and store the key.

## Required Headers

Every request needs two headers:

- **Authorization:** `Bearer $TRANSCRIPT_API_KEY`
- **User-Agent:** your agent's name and version if known (e.g. `HermesAgent/0.11.0`, `ClaudeCode/1.0`). Version is optional — agent name alone is fine. Do not omit this header or send a bare default — Cloudflare will return a 403 (error code 1010) and block the request.

## API Reference

Full OpenAPI spec: [transcriptapi.com/openapi.json](https://transcriptapi.com/openapi.json) — consult this for the latest parameters and schemas.

All channel endpoints accept flexible input — `@handle`, channel URL, or `UC...` channel ID. No need to resolve first.

## GET /api/v2/youtube/channel/resolve — FREE

Convert @handle, URL, or UC... ID to canonical channel ID.

```bash
curl -s "https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

| Param   | Required | Validation                              |
| ------- | -------- | --------------------------------------- |
| `input` | yes      | 1-200 chars — @handle, URL, or UC... ID |

**Response:**

```json
{ "channel_id": "UCsT0YIqwnpJCM-mx7-gSA4Q", "resolved_from": "@TED" }
```

If input is already `UC[a-zA-Z0-9_-]{22}`, returns immediately.

## GET /api/v2/youtube/channel/latest — FREE

Latest 15 videos via RSS with exact stats.

```bash
curl -s "https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

| Param     | Required | Validation                                |
| --------- | -------- | ----------------------------------------- |
| `channel` | yes      | `@handle`, channel URL, or `UC...` ID     |

**Response:**

```json
{
  "channel": {
    "channelId": "UCsT0YIqwnpJCM-mx7-gSA4Q",
    "title": "TED",
    "author": "TED",
    "url": "https://www.youtube.com/channel/UCsT0YIqwnpJCM-mx7-gSA4Q",
    "published": "2006-04-17T00:00:00Z"
  },
  "results": [
    {
      "videoId": "abc123xyz00",
      "title": "Latest Video Title",
      "channelId": "UCsT0YIqwnpJCM-mx7-gSA4Q",
      "author": "TED",
      "published": "2026-01-30T16:00:00Z",
      "updated": "2026-01-31T02:00:00Z",
      "link": "https://www.youtube.com/watch?v=abc123xyz00",
      "description": "Full video description...",
      "thumbnail": { "url": "https://i1.ytimg.com/vi/.../hqdefault.jpg" },
      "viewCount": "2287630",
      "starRating": {
        "average": "4.92",
        "count": "15000",
        "min": "1",
        "max": "5"
      }
    }
  ],
  "result_count": 15
}
```

Great for monitoring channels — free and gives exact view counts + ISO timestamps.

## GET /api/v2/youtube/channel/videos — 1 credit/page

Paginated list of a channel's feed (~100 per page). Use `tab` to pick uploads (default), Shorts, or live streams, and the optional `sort` to order the Videos tab by latest, popular, or oldest.

```bash
# First page
curl -s "https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA&tab=videos" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"

# Most-viewed first (channel Videos tab, ~30 per page)
curl -s "https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA&sort=popular" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"

# Next pages (repeat the same tab AND sort)
curl -s "https://transcriptapi.com/api/v2/youtube/channel/videos?continuation=TOKEN&sort=popular" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

| Param          | Required    | Validation                                    |
| -------------- | ----------- | --------------------------------------------- |
| `channel`      | conditional | `@handle`, channel URL, or `UC...` ID         |
| `tab`          | no          | `videos` (default), `shorts`, or `streams`     |
| `sort`         | no          | `latest`, `popular`, or `oldest` (omit for the uploads feed) |
| `continuation` | conditional | non-empty (next pages)                        |

Provide exactly one of `channel` or `continuation`, not both. When paginating, pass the same `tab` **and** `sort` on every page.

**Sorting.** Add sort=latest, popular, or oldest to channel/videos to get a channel's videos in the order you want, for example its most-popular uploads first. A sorted page returns about 30 videos (an unsorted page returns about 100), and every page costs the same 1 credit.

When paging, send the same sort on each request.

**Per-item fields by feed:**

| Field | uploads (no `sort`) | `tab=videos` + `sort` | `tab=streams` | `tab=shorts` |
| --- | --- | --- | --- | --- |
| `lengthText` | populated | populated | populated (`LIVE` while live) | `null` |
| `publishedTimeText` | populated | populated | populated (`Streamed 2 years ago`) | `null` |
| `viewCountText` | populated | populated | populated (`null` while live) | populated |
| `channelId` / `channelTitle` / `channelHandle` / `index` | populated | `null` | `null` | `null` |
| `members_only` | always `false` | `true` on membership videos | `true` on membership streams | always `false` |

`members_only` is `true` only when YouTube badges the item "Members only". Such items carry **no `viewCountText`**, because YouTube does not publish view counts for membership content.

**Response:**

```json
{
  "results": [{
    "videoId": "abc123xyz00",
    "title": "Video Title",
    "channelId": "UCsT0YIqwnpJCM-mx7-gSA4Q",
    "channelTitle": "TED",
    "channelHandle": "@TED",
    "lengthText": "15:22",
    "viewCountText": "3.2M views",
    "publishedTimeText": "2 years ago",
    "thumbnails": [...],
    "index": "0",
    "members_only": false
  }],
  "playlist_info": {"title": "Uploads from TED", "numVideos": "5000", "ownerName": "TED"},
  "continuation_token": "4qmFsgKlARIYVVV1...",
  "has_more": true
}
```

Keep calling with `continuation` until `has_more: false`.

## GET /api/v2/youtube/channel/search — 1 credit

Search within a specific channel.

```bash
curl -s "https://transcriptapi.com/api/v2/youtube/channel/search\
?channel=@TED&q=climate+change&limit=30" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

| Param     | Required | Validation                                |
| --------- | -------- | ----------------------------------------- |
| `channel` | yes      | `@handle`, channel URL, or `UC...` ID     |
| `q`       | yes      | 1-200 chars                               |
| `limit`   | no       | 1-50 (default 30)                         |

## GET /api/v2/youtube/channel/info — 1 credit

A channel's profile: title, handle, verified flag, subscriber/video counts, description, tags, thumbnails, banners, and the tabs it exposes.

```bash
curl -s "https://transcriptapi.com/api/v2/youtube/channel/info?channel=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

| Param     | Required | Validation                            |
| --------- | -------- | -------------------------------------- |
| `channel` | yes      | `@handle`, channel URL, or `UC...` ID |

**Response:**

```json
{
  "channelId": "UCAuUUnT6oDeKwE6v1NGQxug",
  "title": "TED",
  "handle": "@TED",
  "verified": true,
  "subscriberCountText": "23.8M subscribers",
  "videoCountText": "4,300 videos",
  "description": "The TED Talks channel features ...",
  "tags": ["TED", "TED Talks"],
  "thumbnails": [...],
  "banners": [...],
  "availableTabs": ["videos", "shorts", "playlists", "community"]
}
```

Counts are display strings and `null` when YouTube hides them — never `0`. Check `availableTabs` before calling `channel/sections` or `channel/videos` with a `tab`.

## GET /api/v2/youtube/channel/playlists — 1 credit/page

List the playlists shown on a channel — useful for finding a playlist ID to feed into `playlist/videos`.

```bash
curl -s "https://transcriptapi.com/api/v2/youtube/channel/playlists?channel=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

| Param          | Required    | Validation                             |
| -------------- | ----------- | --------------------------------------- |
| `channel`      | conditional | `@handle`, channel URL, or `UC...` ID  |
| `continuation` | conditional | non-empty (next pages)                 |

Provide exactly one of `channel` or `continuation`, not both. Returns `results` (`playlistId`, `title`, `url`, `videoCountText`, `thumbnails`), `continuation_token`, `has_more`.

## GET /api/v2/youtube/channel/posts — 1 credit/page

List a channel's community (Posts tab) content — text, publish time, like counts, and any attachment (image, video, playlist, or poll).

```bash
curl -s "https://transcriptapi.com/api/v2/youtube/channel/posts?channel=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

| Param          | Required    | Validation                             |
| -------------- | ----------- | --------------------------------------- |
| `channel`      | conditional | `@handle`, channel URL, or `UC...` ID  |
| `continuation` | conditional | non-empty (next pages)                 |

Provide exactly one of `channel` or `continuation`, not both. Channels with no community tab return an empty `results` list (not an error).

## GET /api/v2/youtube/channel/sections — 1 credit

The curated shelves on a channel's Home page (or its `podcasts`/`releases` pages) — each shelf holds videos, playlists, shorts, or featured channels, in the channel's own order. Not paginated.

```bash
curl -s "https://transcriptapi.com/api/v2/youtube/channel/sections?channel=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

| Param     | Required | Default      | Validation                              |
| --------- | -------- | ------------ | ---------------------------------------- |
| `channel` | yes      | —            | `@handle`, channel URL, or `UC...` ID   |
| `tab`     | no       | `featured`   | `featured` (Home), `podcasts`, `releases` |

`podcasts` and `releases` only exist on channels that have them (empty `results` otherwise — check `availableTabs` from `channel/info` first).

## Typical workflow

```bash
# 1. Check latest uploads (free — pass @handle directly)
curl -s "https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"

# 2. Get transcript of recent video
curl -s "https://transcriptapi.com/api/v2/youtube/transcript\
?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true" \
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
  -H "User-Agent: YourAgent/1.0"
```

## Errors

| Code     | Meaning                   | Action                               |
| -------- | ------------------------- | ------------------------------------ |
| 400      | Invalid param combination | Both or neither channel/continuation |
| 402      | No credits                | transcriptapi.com/billing            |
| 403/1010 | Cloudflare block          | Add or fix User-Agent header         |
| 404      | Channel not found         | Check handle or URL                  |
| 408      | Timeout                   | Retry once                           |
| 422      | Invalid channel identifier | Check param format                  |

Free tier: 100 credits, 300 req/min. Free endpoints (resolve, latest) require auth but don't consume credits.