Search endpoint only returns 'snippet' part; use VIDEO_DETAILS for statistics
Search results are capped at 500 total items
Search has higher quota cost (100 units) vs list endpoints (1 unit)
BATCH video details practical limit is ~50 IDs per call; chunk larger sets
3. Manage Playlists
When to use
User wants to create playlists or manage playlist contents
Tool sequence
:
YOUTUBE_LIST_USER_PLAYLISTS
- List user's existing playlists [Optional]
YOUTUBE_CREATE_PLAYLIST
- Create a new playlist [Optional]
YOUTUBE_ADD_VIDEO_TO_PLAYLIST
- Add a video to a playlist [Optional]
YOUTUBE_LIST_PLAYLIST_ITEMS
- List videos in a playlist [Optional]
Key parameters
:
playlistId
Playlist ID ('PL...' for user-created, 'UU...' for uploads)
part
Resource parts to include (e.g., 'snippet,contentDetails')
maxResults
Items per page (1-50)
pageToken
Pagination token from previous response
Pitfalls
:
Do NOT pass channel IDs ('UC...') as playlist IDs; convert 'UC' to 'UU' for uploads
Large playlists require pagination via pageToken; follow nextPageToken until absent
items[].id is not the videoId; use items[].snippet.resourceId.videoId
Creating duplicate playlist names is allowed; check existing playlists first
4. Get Channel and Video Analytics
When to use
User wants to analyze channel performance or video metrics
Tool sequence
:
YOUTUBE_GET_CHANNEL_ID_BY_HANDLE
- Resolve a handle to channel ID [Prerequisite]
YOUTUBE_GET_CHANNEL_STATISTICS
- Get channel subscriber/view/video counts [Required]
YOUTUBE_LIST_CHANNEL_VIDEOS
- List all videos from a channel [Optional]
YOUTUBE_GET_VIDEO_DETAILS_BATCH
- Get per-video statistics [Optional]
YOUTUBE_GET_CHANNEL_ACTIVITIES
- Get recent channel activities [Optional]
Key parameters
:
channelId
Channel ID ('UC...'), handle ('@handle'), or 'me'
forHandle
Channel handle (e.g., '@Google')
id
Comma-separated video IDs for batch details
parts
Resource parts to include (e.g., 'snippet,statistics')
Pitfalls
:
Channel statistics are lifetime totals, not per-period
BATCH video details may return fewer items than requested for private/deleted videos
Response data may be nested under
data
or
data_preview
; parse defensively
contentDetails.duration uses ISO 8601 format (e.g., 'PT4M13S')
5. Manage Subscriptions and Comments
When to use
User wants to subscribe to channels or view video comments
Tool sequence
:
YOUTUBE_SUBSCRIBE_CHANNEL
- Subscribe to a channel [Optional]
YOUTUBE_UNSUBSCRIBE_CHANNEL
- Unsubscribe from a channel [Optional]
YOUTUBE_LIST_USER_SUBSCRIPTIONS
- List subscriptions [Optional]
YOUTUBE_LIST_COMMENT_THREADS
- List comments on a video [Optional]
Key parameters
:
channelId
Channel to subscribe/unsubscribe
videoId
Video ID for comment threads
maxResults
Results per page
pageToken
Pagination token
Pitfalls
:
Subscribing to an already-subscribed channel may return an error
Comment threads return top-level comments with up to 5 replies each
Comments may be disabled on some videos
Unsubscribe requires the subscription ID, not the channel ID
Common Patterns
Channel ID Resolution
Handle to Channel ID
:
1. Call YOUTUBE_GET_CHANNEL_ID_BY_HANDLE with '@handle'
2. Extract channelId from response
3. Use in subsequent channel operations
Uploads Playlist
:
1. Get channel ID (starts with 'UC')
2. Replace 'UC' prefix with 'UU' to get uploads playlist ID
3. Use with LIST_PLAYLIST_ITEMS to enumerate all videos
Pagination
Set
maxResults
(max 50 per page)
Check response for
nextPageToken
Pass token as
pageToken
in next request
Continue until
nextPageToken
is absent
Batch Video Details
Collect video IDs from search or playlist listings
Chunk into groups of ~50 IDs
Call GET_VIDEO_DETAILS_BATCH per chunk
Merge results across chunks
Known Pitfalls
Quota Management
:
YouTube API has a daily quota limit (default 10,000 units)
Upload = 1600 units; search = 100 units; list = 1 unit
Prefer list endpoints over search when possible
Monitor quota usage to avoid hitting daily limits
ID Formats
:
Video IDs: 11-character alphanumeric strings
Channel IDs: Start with 'UC' followed by 22 characters
Playlist IDs: Start with 'PL' (user) or 'UU' (uploads)
Do not confuse channel IDs with playlist IDs
Thumbnails
:
Custom thumbnails require channel phone verification
Must be JPG, PNG, or GIF; under 2MB
Recommended: 1280x720 resolution (16:9 aspect ratio)
Response Parsing
:
Statistics values are returned as strings, not integers; cast before math
Duration uses ISO 8601 format (PT#H#M#S)
Batch responses may wrap data under different keys
Quick Reference
Task
Tool Slug
Key Params
Upload video
YOUTUBE_UPLOAD_VIDEO
title, description, tags, categoryId, privacyStatus, videoFilePath
Update video
YOUTUBE_UPDATE_VIDEO
video_id, title, description, tags
Set thumbnail
YOUTUBE_UPDATE_THUMBNAIL
videoId, thumbnailUrl
Search YouTube
YOUTUBE_SEARCH_YOU_TUBE
q, type, maxResults
Video details
YOUTUBE_VIDEO_DETAILS
id, part
Batch video details
YOUTUBE_GET_VIDEO_DETAILS_BATCH
id, parts
List playlists
YOUTUBE_LIST_USER_PLAYLISTS
maxResults, pageToken
Create playlist
YOUTUBE_CREATE_PLAYLIST
(check schema)
Add to playlist
YOUTUBE_ADD_VIDEO_TO_PLAYLIST
(check schema)
List playlist items
YOUTUBE_LIST_PLAYLIST_ITEMS
playlistId, maxResults
Channel statistics
YOUTUBE_GET_CHANNEL_STATISTICS
id/forHandle/mine
List channel videos
YOUTUBE_LIST_CHANNEL_VIDEOS
channelId, maxResults
Channel ID by handle
YOUTUBE_GET_CHANNEL_ID_BY_HANDLE
channel_handle
Subscribe
YOUTUBE_SUBSCRIBE_CHANNEL
channelId
List subscriptions
YOUTUBE_LIST_USER_SUBSCRIPTIONS
(check schema)
List comments
YOUTUBE_LIST_COMMENT_THREADS
videoId
Channel activities
YOUTUBE_GET_CHANNEL_ACTIVITIES
(check schema)
When to Use
This skill is applicable to execute the workflow or actions described in the overview.