resolve_youtube_channel
Convert YouTube channel references like handles, URLs, or usernames into official channel IDs and upload playlist IDs for accessing public channel data.
Instructions
Resolve a YouTube channel reference into a concrete channelId.
What this tool does:
- Converts a user-facing channel identifier into a YouTube channelId.
- Optionally returns the channel's uploadsPlaylistId, which enables
listing all uploaded videos via playlistItems.list.
Supported input formats (examples):
- Handle: @GoogleDevelopers
- Handle URL: https://www.youtube.com/@GoogleDevelopers
- Channel ID URL: https://www.youtube.com/channel/UC...
- Legacy username URL: https://www.youtube.com/user/SomeUsername
Parameters:
channel_ref:
Channel identifier in one of the supported formats.
resolution_mode:
- strict (default): ambiguous inputs are rejected with an
explainable error. This prevents "silent wrong channel" bugs.
- best_effort: ambiguous inputs return a short list of candidate
channels. (This mode may use the Search API and can be expensive.)
include_uploads_playlist:
If true, attempts to include uploadsPlaylistId in the output.
Returns (structured JSON): - channelId: string | null - title: string | null - handle: string | null - uploadsPlaylistId: string | null - warnings: string[] - candidates: {channelId,title,handle}[]
Failure modes: - Missing API key: raises error "YOUTUBE_API_KEY not configured". - Ambiguous/unsupported input (strict): raises ValueError with guidance.
Safety notes: - Does not perform destructive actions. - Does not access private channel data.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| channel_ref | Yes | ||
| resolution_mode | No | strict | |
| include_uploads_playlist | No |