YouTube

Video. Search videos, channels, and playlists, manage video details and playlists, moderate comments, and handle captions.

Measured routing accuracy

49 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 34 cases written by hand and 15 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

oauth2

Tools

34 action tools. The catalog-wide slug is youtube.<tool>, which is what search_tools returns and call_tool takes.

youtube.search_videos

Search YouTube for videos matching a keyword or phrase. Use when the user wants to find, look up, or discover videos by topic or title and doesn't already have a video id. Filter to one channel's uploads with channel_id. For a channel or playlist by name instead, use search_channels or search_playlists.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /search.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "look up a clip about this topic", "find something on this on youtube", "hunt down a tutorial on this", "pull up a video by this creator", "what's out there on this subject".

youtube.search_channels

Search YouTube for channels matching a name or keyword. Use when the user wants to find a creator or channel and doesn't already have its channel id. For videos instead, use search_videos.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /search.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who makes videos about this", "find that creator's page", "locate this account by name", "track down which uploader this is".

youtube.search_playlists

Search YouTube for playlists matching a keyword or phrase. Use when the user wants to find a playlist by topic or title and doesn't already have its playlist id. For videos or channels instead, use search_videos or search_channels.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /search.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "is there a mix of videos on this already", "find a curated set on this theme", "look for a compilation someone made", "dig up a binge-watch list".

youtube.get_video

Get full details for one video by id: title, description, channel, duration, and view/like/comment counts. Use when the user already names or links a specific video. To find a video's id from a title, use search_videos.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /videos.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what's this clip about exactly", "pull the stats on this upload", "how long does this run and who posted it", "tell me about this specific upload".

youtube.list_popular_videos

List the most popular videos on YouTube right now, optionally for one region and category. Use when the user asks what's trending, popular, or viral. For an ongoing search by topic instead, use search_videos.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /videos.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what's blowing up right now", "show me the charts for this", "what's everyone watching today", "what's hot in this category right now".

youtube.list_video_categories

List the video categories YouTube defines for a region, like Music, Gaming, or Comedy, with their ids. Use before list_popular_videos when the user wants trending videos in a specific category.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /videoCategories.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what genres does youtube split things into", "show the topic buckets for this country", "what sections exist for browsing".

youtube.update_video

Change a video's title, description, tags, category, or privacy status. Use when the user wants to edit, rename, retitle, or update a video they own. Only fields you pass change; omitted fields keep their current value.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube. Calls PUT /videos.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "change the title on my upload", "fix the blurb under my clip", "swap out the tags on this upload", "make my video public instead of private", "rewrite the summary on this one".

youtube.delete_video

Permanently delete a video from a channel. Use when the user wants to delete, remove, or take down a video they own. Irreversible: the video, its views, and its comments are gone for good, and there is no undo.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://www.googleapis.com/auth/youtube. Calls DELETE /videos.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "take this upload down for good", "get rid of this clip permanently", "wipe this off my channel".

youtube.rate_video

Like, dislike, or clear the connected account's rating on a video. Use when the user wants to like, dislike, thumbs up, thumbs down, or un-rate a video. To check the current rating first, use get_video_rating.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls POST /videos/rate.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "give this a thumbs up", "I don't like this one", "undo my reaction to this", "hit like on this upload".

youtube.get_video_rating

Check whether the connected account has liked or disliked a video. Use when the user asks if they've already rated, liked, or disliked something before rating it again.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls GET /videos/getRating.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did I already thumbs up this one", "what did I react with here", "check my reaction on this clip".

youtube.get_channel

Get details for a channel: name, description, subscriber count, video count, and its uploads playlist id. Pass channel_id or handle for someone else's channel, or mine=true for the connected account's own channel. Use when the user asks about a creator or their own channel.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /channels.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who runs this page", "how many subscribers does this creator have", "tell me about my own account here", "what's this uploader's about section say".

youtube.update_channel

Change the connected account's own channel branding: its description, keywords, or default language. Use when the user wants to edit, or update their channel's about section. Cannot rename the channel or change its handle; that is done in YouTube Studio, not the API.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube. Calls PUT /channels.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "rewrite my about section", "change the keywords on my page", "edit what shows on my channel's info tab".

youtube.get_playlist

Get details for one playlist by id: title, description, owner, and video count. Use when the user names or links a specific playlist. For the videos inside it, use list_playlist_items.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /playlists.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who put this mix together", "how many clips are in this compilation", "details on this curated list".

youtube.list_playlists

List playlists owned by a channel, or the connected account's own playlists with mine=true. Use when the user asks what playlists a channel or their own account has. For one playlist's own details, use get_playlist.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /playlists.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what compilations does this creator have", "show all the mixes I've made", "what curated sets exist on my own account".

youtube.create_playlist

Create a new playlist on the connected account's channel. Use when the user wants to make, start, or set up a new playlist. Add videos to it afterward with add_playlist_item.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube. Calls POST /playlists.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "start a new compilation", "set up a fresh mix", "build a new curated list".

youtube.update_playlist

Change a playlist's title, description, or privacy status. Use when the user wants to rename or edit a playlist's details. Does not touch its videos; for that use add_playlist_item or delete_playlist_item.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube. Calls PUT /playlists.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "rename my compilation", "change the blurb on this mix", "make this curated list public".

youtube.delete_playlist

Permanently delete a playlist the connected account owns. Use when the user wants to delete or remove a whole playlist. Irreversible: the playlist is gone, though its videos are unaffected. To remove just one video from a playlist instead, use delete_playlist_item.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://www.googleapis.com/auth/youtube. Calls DELETE /playlists.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "get rid of this whole mix", "wipe out this compilation entirely", "trash this curated list for good".

youtube.list_playlist_items

List the videos inside a playlist, in playlist order. Use when the user wants to see, read, or browse what's in a playlist, including a channel's uploads playlist for "all their videos". For the playlist's own title and details rather than its contents, use get_playlist.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /playlistItems.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what clips are inside this mix", "see every upload from this channel in order", "browse the contents of this compilation".

youtube.add_playlist_item

Add a video to a playlist, optionally at a specific position. Use when the user wants to add, put, or include a video in a playlist. To remove one instead, use delete_playlist_item.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube. Calls POST /playlistItems.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "drop this clip into my mix", "toss this upload onto the compilation", "slot this video into the list".

youtube.update_playlist_item

Move a video already in a playlist to a new position. Use when the user wants to reorder, move, or resort a playlist's videos. To add or remove a video instead, use add_playlist_item or delete_playlist_item.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube. Calls PUT /playlistItems.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "move this clip up in the mix", "reorder where this upload sits", "shuffle this video's spot in the compilation".

youtube.delete_playlist_item

Remove one video from a playlist. Use when the user wants to remove, delete, or take a video out of a playlist. The video itself is not deleted, only its entry in this playlist. Undoable by adding it back with add_playlist_item.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://www.googleapis.com/auth/youtube. Calls DELETE /playlistItems.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull this clip out of the mix", "take this upload off the compilation", "drop this one video from the list".

youtube.list_video_comments

List top-level comments on a video, most relevant first. Use when the user wants to read, see, or check the comments on a video. Each result includes the reply count; fetch replies with list_comment_replies.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /commentThreads.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what are people saying under this clip", "check the discussion on this upload", "see what viewers wrote here".

youtube.list_channel_comments

List comment threads across every video on a channel, most recent first. Use when the user wants to check, moderate, or catch up on all comments on their channel rather than one specific video. For one video's comments, use list_video_comments instead.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /commentThreads.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "catch me up on every discussion across my uploads", "what are people saying on all my clips", "review feedback across the whole channel".

youtube.list_comment_replies

List the replies under one top-level comment. Use when the user wants to see, read, or check the replies on a specific comment. For the top-level comments themselves, use list_video_comments.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.readonly. Calls GET /comments.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what did people say back to this remark", "see the responses under this note", "any follow-ups to this one".

youtube.create_comment_thread

Post a new top-level comment on a video. Use when the user wants to comment on, post to, or leave a comment under a video. To reply to an existing comment instead, use reply_to_comment.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls POST /commentThreads.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "leave a note under this clip", "write something on this upload", "drop a remark on this video".

youtube.reply_to_comment

Post a reply under an existing top-level comment. Use when the user wants to reply to, respond to, or answer a comment. For a new top-level comment instead, use create_comment_thread.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls POST /comments.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "write back to this viewer", "respond to what they said here", "answer this remark".

youtube.update_comment

Edit the text of a comment or reply the connected account posted. Use when the user wants to edit, fix, or change something they already commented. To remove it entirely instead, use delete_comment.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls PUT /comments.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fix a typo in what I wrote", "change what I said earlier", "correct my earlier remark".

youtube.delete_comment

Permanently delete a comment or reply. Use when the user wants to delete or remove a comment, either one they posted or, as a channel owner moderating their own video, one someone else posted. Irreversible.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls DELETE /comments.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "take down this remark", "get rid of what someone wrote", "wipe this note off the clip".

youtube.set_comment_moderation_status

Approve, hold for review, or mark a comment as spam, as the channel owner moderating comments on their own video. Use when the user wants to moderate, approve, reject, or flag a comment as spam without deleting it outright.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls POST /comments/setModerationStatus.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "hold this remark for review", "mark this as spam", "approve this held comment", "block this person from writing more here".

youtube.list_captions

List the caption tracks available for a video, with their language and whether each is a draft. Use when the user asks what subtitles, captions, or transcripts exist for a video. To fetch a track's actual text, use download_caption.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls GET /captions.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what languages does this clip have text in", "is there a transcript available for this", "check what subtitle tracks exist".

youtube.download_caption

Download the text of one caption track by its id. Use when the user wants the subtitles, captions, or transcript text itself, not just which tracks exist. Find the track id first with list_captions. Returns the raw subtitle file content, not JSON.

Class read (reads only). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls GET /captions/{{params.caption_id}}.

Arguments:

Also retrieved by: "grab the actual subtitle wording", "pull the words that scroll on screen", "fetch the srt file contents".

youtube.upload_caption

Add a new caption track to a video in a given language. Use when the user wants to add, upload, or attach subtitles or captions to a video. Pass the track content as SRT or VTT text; it is sent as a base64 JSON field, not a native file upload. To replace an existing track's text instead, use update_caption.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls POST /captions.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "attach a transcript in another language", "give this clip subtitles", "add closed captions to my upload".

youtube.update_caption

Replace the text of an existing caption track, or flip it between draft and published. Use when the user wants to fix, correct, or republish a caption track's content. To add a brand-new track instead, use upload_caption.

Class write (writes, no confirmation needed). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls PUT /captions.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fix the wording in the subtitle track", "publish the draft transcript", "correct the closed captions".

youtube.delete_caption

Permanently delete a caption track from a video. Use when the user wants to delete, remove, or take down a set of subtitles or captions. Irreversible; re-add with upload_caption if needed again.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes https://www.googleapis.com/auth/youtube.force-ssl. Calls DELETE /captions.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "remove the transcript track", "get rid of the subtitle file", "take off the closed captions".