From b2a1471efebe3fe77ce7145dc83233c23ad1aacc Mon Sep 17 00:00:00 2001 From: therohitdas <43847374+therohitdas@users.noreply.github.com> Date: Mon, 21 Sep 2026 10:58:07 +0000 Subject: [PATCH] docs: channel/videos sort + members_only across the plugin's API surface All four places this repo enumerates the endpoint now carry it: README tool 8, the SKILL.md routing table plus credit-hygiene notes, references/mcp-tools.md and references/rest-api.md. Each leads with the same framing: existing calls are untouched, and sort=latest is a different view (the Videos tab, Shorts excluded) rather than a re-ordering of the uploads feed. Verified empirically on three channels: 0 of the Shorts a channel publishes appear in any sorted feed, while 43/48 (@TED), 12/40 (@NASA) and 30/48 (@natgeo) appear in the unsorted uploads feed. Per-tab field presence recorded honestly: tab=streams carries lengthText and publishedTimeText, tab=shorts returns null for both, and the channel-tab feeds null out channelId/channelTitle/channelHandle/index. Docs only, no version bump. Co-Authored-By: CRHQ --- README.md | 21 ++++++++++++++++++++- skills/youtube/SKILL.md | 5 +++++ skills/youtube/references/mcp-tools.md | 21 ++++++++++++++++++++- skills/youtube/references/rest-api.md | 25 +++++++++++++++++++++++-- 4 files changed, 68 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a435fdf..28c27d7 100644 --- a/README.md +++ b/README.md @@ -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` diff --git a/skills/youtube/SKILL.md b/skills/youtube/SKILL.md index 6d7e99d..641368d 100644 --- a/skills/youtube/SKILL.md +++ b/skills/youtube/SKILL.md @@ -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 | @@ -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 diff --git a/skills/youtube/references/mcp-tools.md b/skills/youtube/references/mcp-tools.md index c823953..a51ebd4 100644 --- a/skills/youtube/references/mcp-tools.md +++ b/skills/youtube/references/mcp-tools.md @@ -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`. diff --git a/skills/youtube/references/rest-api.md b/skills/youtube/references/rest-api.md index 4bf2bf3..aeb22d4 100644 --- a/skills/youtube/references/rest-api.md +++ b/skills/youtube/references/rest-api.md @@ -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 @@ -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