youtube_query

The main entry point for YouTube in chat. Paste a URL, @handle, playlist, or search text — or set goal/intent explicitly. Handles search, channels, playlists, comments, and multi-video creator advice in one call.

When to use

User pastes any YouTube link and intent isn't obvious yet
Search or research across YouTube
Latest uploads from a channel
What a creator teaches about a topic (goal=advice)
Comments, playlist items, channel/video metadata

For a single-video summary with chapters, use summarize_video instead. For exact caption text, use get_transcript.

Quick examples

youtube_query(intent="auto", ref="https://www.youtube.com/watch?v=VIDEO_ID")

Auto-detects video, channel, playlist, or search from the ref string.

ref formats (intent=auto)

Pass anything the user pasted into ref. The server recognizes:

Video URLs: youtube.com/watch?v=, youtu.be/, youtube.com/shorts/
Channel: @handle, youtube.com/channel/UC…, /c/, /user/
Playlist: youtube.com/playlist?list=
Plain search text (no URL) — treated as a search query

Parameters

Parameter	Type	Default	Description
intent	enum	auto	Routing mode. Use auto for pasted refs; set explicitly for advanced control.
goal	enum	auto	User-friendly shortcut that maps to intent. Prefer this in chat-driven flows.
ref	string \| null	null	Primary reference — URL, @handle, playlist, or search text.
query	string \| null	null	Search query when intent is research/search.
channel_ref	string \| null	null	Channel handle or URL for latest/advice/channel_info.
video_ref	string \| null	null	Video URL or ID for video_info, comments.
playlist_ref	string \| null	null	Playlist URL or ID for playlist_videos.
max_results	integer	5	Cap on videos, comments, or search results returned.
page_token	string \| null	null	Pagination token from a previous response.
exclude_shorts	boolean	true	Filter YouTube Shorts from channel latest and advice.
include_stats	boolean	true	Include view/like counts where available.
result_type	video \| channel \| playlist	video	Search result filter.
order	enum	relevance	Search sort: relevance, date, viewCount, rating, title, videoCount.
comment_order	relevance \| time	relevance	Sort order for video comments.
include_replies	boolean	true	Include reply threads on comments.
channel_id	string \| null	null	Raw channel ID when you already resolved it.
include_full_description	boolean	false	Return full video/channel description (more tokens).
depth	brief \| detailed	brief	Detail level for advice synthesis.
topic_filter	string \| null	null	Narrow creator advice to a topic, e.g. "hiring" or "kubernetes".

intent values

auto

Detect from ref. Default and best for pasted links.

latest_channel

Recent uploads from channel_ref. Pair with exclude_shorts.

research / search

Topic search via query. Use order=viewCount for popularity ranking.

creator_insights

Multi-video synthesis — same as goal=advice. One call, multiple videos.

video_comments

Top comments on video_ref.

playlist_videos

List videos in playlist_ref.

video_info / channel_info

Metadata only — title, description, stats. No transcript.

What you get back

Response shape depends on intent. Common fields:

Video list with titles, IDs, durations, view counts
Channel name, handle, subscriber count
Comment text, author, like count
For advice: synthesized themes across videos with source video IDs
next_steps[] — e.g. "call summarize_video on video X" or "paginate with page_token"

Quota tips

goal=advice— Cheaper than N summarize_video calls
max_results=5— Default is conservative; raise only when needed
goal=research— One broad search beats many narrow ones
include_full_description=false— Saves tokens and API units

Quota & billing · Example prompts