Skip to content

docs: channel/videos sort + members_only across the plugin's API surface #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
therohitdas merged 1 commit into from
Sep 21, 2026
Merged

docs: channel/videos sort + members_only across the plugin's API surface #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -382,14 +382,33 @@ Search inside one specific channel for videos matching a query.

### 8. `list_channel_videos`

List a channel's feed, paginated. Use `tab` to choose the uploads feed (default, ~100/page), Shorts, or live streams (~48/page). Ideal for building databases or bulk transcript extraction.
List a channel's feed, paginated. Use `tab` to choose the uploads feed (default, ~100/page), Shorts, or live streams (~48/page), and the optional `sort` to order the Videos tab by latest, popular, or oldest. Ideal for building databases or bulk transcript extraction.

| Parameter | Type | Default | Description |
| -------------- | ------ | ------------ | ------------------------------------ |
| `channel` | string | **required** (first call) | `@handle`, channel URL, or `UC…` ID |
| `tab` | string | `"videos"` | `videos` (uploads), `shorts`, or `streams`. Repeat the same `tab` when paginating. |
| `sort` | string | `null` | `latest`, `popular`, or `oldest`. Omit for the uploads feed. Repeat the same value when paginating. |
| `continuation` | string | `null` | Pagination token |

Existing calls are untouched: omitting sort returns the uploads feed exactly as before. sort=latest is a different view (YouTube's Videos tab, Shorts excluded), not a re-ordering of it.

| | `tab: "videos"`, no `sort` | `tab: "videos"` + any `sort` |
| --- | --- | --- |
| Source | uploads playlist | channel Videos tab |
| Page size | ~100 | ~30 |
| `playlist_info` | populated | `null` |
| Shorts | mixed in | excluded (use `tab: "shorts"`) |
| Members-only videos | excluded | included, flagged `members_only: true` |

Sort reads ~3.3x more pages (~30/page vs ~100), so it costs ~3.3x credits. Use it when you need ordering; most integrations don't.

`tab: "shorts"` and `tab: "streams"` read the same feed either way, so there `sort` only reorders.

Every item carries **`members_only`**: `true` only when YouTube badges the video "Members only", and those items have no `viewCountText`. It is always `false` on the uploads feed, on `tab: "shorts"`, and on playlists.

Items from `tab: "streams"` carry `lengthText` and `publishedTimeText` (for example `Streamed 2 years ago`, or `LIVE` and a watching count while live). `tab: "shorts"` returns `null` for both, because YouTube's Shorts grid publishes neither. On the channel-tab feeds, `channelId`, `channelTitle`, `channelHandle` and `index` are `null`.

**Cost:** 1 credit per page.

### 9. `list_channel_playlists`
Expand Down
5 changes: 5 additions & 0 deletions skills/youtube/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ credits, no card.
| What a creator posted recently | `get_channel_latest_videos` | `GET /youtube/channel/latest` | **free** |
| Find something inside one channel | `search_channel_videos` | `GET /youtube/channel/search` | 1 / page |
| A channel's entire upload history, Shorts, or live streams | `list_channel_videos` | `GET /youtube/channel/videos` | 1 / page |
| A channel's back catalogue ranked by views, or walked oldest-first | `list_channel_videos` + `sort` | `GET /youtube/channel/videos?sort=` | 1 / page |
| The playlists on a channel | `list_channel_playlists` | `GET /youtube/channel/playlists` | 1 / page |
| A channel's community posts | `list_channel_posts` | `GET /youtube/channel/posts` | 1 / page |
| A channel's curated Home/podcasts/releases shelves | `get_channel_sections` | `GET /youtube/channel/sections` | 1 |
Expand Down Expand Up @@ -94,6 +95,10 @@ Successful calls cost 1 credit unless a tool states otherwise below. Failed and

- **`get_channel_latest_videos` is free.** Reach for it first for anything about recent
uploads. Use `list_channel_videos` only when the user genuinely wants the whole catalogue.
- `list_channel_videos` takes an optional `sort` (`latest` / `popular` / `oldest`). Existing calls are untouched: omitting sort returns the uploads feed exactly as before. sort=latest is a different view (YouTube's Videos tab, Shorts excluded), not a re-ordering of it.
Omitted reads the uploads playlist (~100/page, Shorts mixed in, members-only videos excluded);
any value reads the channel Videos tab (~30/page, long-form only, members-only videos included
and flagged `members_only`). They are different sets, not one list in two orders. A sorted page holds ~30 items instead of ~100, so paging a whole catalogue with `sort` set costs roughly 3.3x the pages and 3.3x the credits. Omit `sort` when you just want newest-first.
- **Search, then transcribe selectively.** Transcribing a whole page of search results is the
single most common way to waste credits. Pick the best 2-3 hits and pull those.
- **Search inside a channel** with `search_channel_videos` rather than listing every video and
Expand Down
21 changes: 20 additions & 1 deletion skills/youtube/references/mcp-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,14 +159,33 @@ Always better than listing a whole channel and filtering client-side.
## `list_channel_videos`: 1 credit per page

A channel's feed, paginated. Use `tab` to choose the uploads feed (default, ~100/page), Shorts,
or live streams (~48/page).
or live streams (~48/page), and the optional `sort` to order the Videos tab.

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `channel` | string | **required** (first call) | `@handle`, channel URL, or `UC…` ID |
| `tab` | string | `"videos"` | `videos` (uploads), `shorts`, or `streams`. Repeat the same `tab` when paginating. |
| `sort` | string | `null` | `latest`, `popular`, or `oldest`. Omit for the uploads feed. Repeat the same value when paginating. |
| `continuation` | string | `null` | Pagination token |

Existing calls are untouched: omitting sort returns the uploads feed exactly as before. sort=latest is a different view (YouTube's Videos tab, Shorts excluded), not a re-ordering of it.

| | `tab: "videos"`, no `sort` | `tab: "videos"` + any `sort` |
| --- | --- | --- |
| Source | uploads playlist | channel Videos tab |
| Page size | ~100 | ~30 |
| `playlist_info` | populated | `null` |
| Shorts | mixed in | excluded (use `tab: "shorts"`) |
| Members-only videos | excluded | included, flagged `members_only: true` |

They are different sets, not one list in two orders. A sorted page holds ~30 items instead of ~100, so paging a whole catalogue with `sort` set costs roughly 3.3x the pages and 3.3x the credits. Omit `sort` when you just want newest-first.

`tab: "shorts"` and `tab: "streams"` read the same feed either way, so there `sort` only reorders.

Every item carries **`members_only`**: `true` only when YouTube badges the video "Members only", and those items have no `viewCountText`. It is always `false` on the uploads feed, on `tab: "shorts"`, and on playlists.

Items from `tab: "streams"` carry `lengthText` and `publishedTimeText` (for example `Streamed 2 years ago`, or `LIVE` and a watching count while live). `tab: "shorts"` returns `null` for both, because YouTube's Shorts grid publishes neither. On the channel-tab feeds, `channelId`, `channelTitle`, `channelHandle` and `index` are `null`.

Only when the user genuinely wants the whole catalogue. For recent uploads use
`get_channel_latest_videos` (free); to find something specific use `search_channel_videos`.

Expand Down
25 changes: 23 additions & 2 deletions skills/youtube/references/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,20 +179,40 @@ Returns exact `viewCount` and ISO `published` timestamps.
### Channel videos (paginated): 1 credit per page

```http
GET /youtube/channel/videos?channel=@NASA # first page, ~100 videos
GET /youtube/channel/videos?channel=@NASA # first page, ~100 videos
GET /youtube/channel/videos?channel=@NASA&tab=shorts
GET /youtube/channel/videos?continuation=TOKEN # subsequent pages
GET /youtube/channel/videos?channel=@NASA&sort=popular # Videos tab, most-viewed first, ~30
GET /youtube/channel/videos?continuation=TOKEN&sort=popular # repeat tab AND sort
```

| Param | Required | Default | Values |
| --- | --- | --- | --- |
| `channel` | conditional | - | first page only |
| `tab` | no | `videos` | `videos` (uploads), `shorts`, `streams`. Repeat the same `tab` when paginating. |
| `sort` | no | - | `latest`, `popular`, `oldest`. Omit for the uploads feed. Repeat the same value when paginating. |
| `continuation` | conditional | - | subsequent pages |

Provide **exactly one** of `channel` or `continuation`. The response carries
`continuation_token` and `has_more`.

Existing calls are untouched: omitting sort returns the uploads feed exactly as before. sort=latest is a different view (YouTube's Videos tab, Shorts excluded), not a re-ordering of it.

| | `tab=videos`, no `sort` | `tab=videos` + any `sort` |
| --- | --- | --- |
| Source | uploads playlist | channel Videos tab |
| Page size | ~100 | ~30 |
| `playlist_info` | populated | `null` |
| Shorts | mixed in | excluded (use `tab=shorts`) |
| Members-only videos | excluded | included, flagged `members_only: true` |

They are different sets, not one list in two orders. A sorted page holds ~30 items instead of ~100, so paging a whole catalogue with `sort` set costs roughly 3.3x the pages and 3.3x the credits. Omit `sort` when you just want newest-first. `tab=shorts` / `tab=streams` read the same feed either way; there `sort` only reorders.

Every item carries `members_only`, `true` only when YouTube badges it "Members only", and those
items have no `viewCountText`. `tab=streams` items carry `lengthText` and `publishedTimeText`
(for example `Streamed 2 years ago`); `tab=shorts` returns `null` for both, because YouTube's
Shorts grid publishes neither. On the channel-tab feeds, `channelId`, `channelTitle`,
`channelHandle` and `index` are `null`.

### Search within a channel: 1 credit per page

```http
Expand Down Expand Up @@ -283,6 +303,7 @@ Free endpoints still require an active plan with at least one credit available.
| `q` | 1-200 characters |
| `type` (search) | `video`, `channel`, `playlist`, `movie` |
| `tab` (channel/videos) | `videos`, `shorts`, `streams` |
| `sort` (channel/videos) | `latest`, `popular`, `oldest` (omit for the uploads feed) |
| `tab` (channel/sections) | `featured`, `podcasts`, `releases` |

## Worked example: research workflow
Expand Down
Loading