List Subscriptions
youtube_list_subscriptionsRetrieve your YouTube subscriptions with sorting by relevance, unread activity, or alphabetically. Supports pagination and output in markdown or JSON format.
Instructions
List all channels that the authenticated user is subscribed to, using the YouTube Data API v3 subscriptions.list endpoint with mine:true.
Args:
order— Sort order for the returned list. One of:relevance(default) — YouTube's relevance ranking.unread— Channels with new activity appear first.alphabetical— Alphabetical by channel title.
maxResults— Number of subscriptions to return per page (1–50, default 25).pageToken— Pagination cursor. Pass thenextPageTokenfrom a previous response to retrieve the next page. Optional.response_format—"markdown"(default, human-readable summary) or"json"(full structured data).
Returns (JSON shape):
{
"nextPageToken": "string | null",
"pageInfo": { "totalResults": 142, "resultsPerPage": 25 },
"items": [
{
"id": "subscription-resource-id",
"snippet": {
"publishedAt": "2021-03-10T08:00:00Z",
"title": "Channel Title",
"description": "Channel description...",
"resourceId": { "kind": "youtube#channel", "channelId": "UCxxxxxx" },
"thumbnails": { "default": { "url": "https://..." } }
},
"contentDetails": {
"totalItemCount": 312,
"newItemCount": 5,
"activityType": "all"
}
}
]
}Examples:
List first 25 subscriptions alphabetically:
{ "order": "alphabetical" }Find channels with new videos:
{ "order": "unread", "maxResults": 10 }Paginate to the next page:
{ "pageToken": "<nextPageToken from previous call>" }
Common Errors:
401 / 403 authError— Credentials missing or expired; re-runnpm run auth.403 forbidden— The authenticated account does not have permission to list its own subscriptions; check scopes includehttps://www.googleapis.com/auth/youtube.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | Sort order: "relevance" (default), "unread" (new activity first), or "alphabetical". | relevance |
| maxResults | No | Number of subscriptions to return per page (1–50). Default: 25. | |
| pageToken | No | Pagination cursor. Pass the nextPageToken from a previous response to get the next page. | |
| response_format | No | Output format: "markdown" (default, human-readable) or "json" (full structured data). | markdown |