Discovery Search

Terminated Channels

TOOL search_terminated_channels

Search terminated/deleted YouTube channels. Returns channel metadata, growth metrics at time of termination, and top videos. Available on all plans.

Example prompt

"Search for terminated 'roblox' channels that had over 100k subscribers"

Parameter	Type	Default	Description
q	string	required	Search query. Matches channel titles and video titles. Comma-separated for multiple keywords.
languages	string	null	Filter by language. Comma-separated.
sort	string	date_desc	Sort: `{field}_{asc\|desc}`. Fields: `subs`, `views`, `videos`, `age`, `views_24h`, `subs_24h`, `views_48h`, `date`, `similarity`
page	integer	1	Page number (1-indexed, max 20)
per_page	integer	50	Results per page (max 50)
min_subs	integer	null	Minimum subscriber count
max_subs	integer	null	Maximum subscriber count
min_views	integer	null	Minimum total view count
max_views	integer	null	Maximum total view count
min_avg_views	integer	null	Minimum average views per video
max_avg_views	integer	null	Maximum average views per video
min_age	integer	null	Minimum channel age in days
max_age	integer	null	Maximum channel age in days
min_uploads	integer	null	Minimum number of videos
max_uploads	integer	null	Maximum number of videos
monetized	string	null	Filter by monetization: `yes` or `no`

Viral Videos

TOOL search_viral_videos

Find viral videos — by similarity to a query/video, or by pure filters. Three modes: (1) pass search for a topic/channel query, (2) pass video_url to find similar videos, (3) omit both and browse by filters alone (e.g. “biggest outliers from the last 7 days with 100k+ views”). To check if specific channels have viral videos, pass their channel_ids from a prior search. Filter by video views, channel size, growth metrics, upload recency, and outlier score (a video's views ÷ its channel's average views per video — e.g. 3.2 means the video got 3.2× the channel's typical views). Each result includes an outlier_score field; sort by outlier_score to surface the biggest over-performers.

Example prompt

"Find viral Shorts videos about cooking uploaded in the last 7 days with over 1 million views"

Parameter	Type	Default	Description
search	string	null	Text search query — uses title similarity matching. Pass exact video titles, not paraphrased keywords. Optional — omit along with `video_url` to browse by filters alone.
keyword	string	null	Alias for `search` (deprecated, kept for back-compat with the REST endpoint's param name). If both are set, `search` wins.
video_url	string	null	YouTube video URL (watch, shorts, or youtu.be link). Finds similar videos based on the given video. Optional.
content_type	string	shorts	Content type: `shorts` or `longform`
channel_ids	string	null	Comma-separated channel IDs to filter by (e.g. from a prior `search_shorts_channels` result). When provided, only returns viral videos from these specific channels.
sort_by	string	similarity	Sort: `similarity` (default, best for finding most relevant videos — requires `search` or `video_url`; auto-swaps to `outlier_score` for pure-filter browsing), `views` (most viewed), `recent` (newest fetched), `upload_date` (newest uploaded), `outlier_score` (biggest over-performers — views vs channel average)
page	integer	1	Page number (1-indexed, max 20)
per_page	integer	50	Results per page (max 50)
min_video_views	integer	10000	Minimum video view count. Default matches the system's natural floor.
max_video_views	integer	null	Maximum video view count
min_subs	integer	null	Minimum channel subscriber count
max_subs	integer	50000000	Maximum channel subscriber count
min_uploads	integer	null	Minimum channel video count
max_uploads	integer	null	Maximum channel video count
min_channel_age	integer	null	Minimum channel age in days
max_channel_age	integer	null	Maximum channel age in days
uploaded_within_days	integer	364	Only include videos uploaded within this many days. E.g. `7` = last week, `30` = last month.
uploaded_before_days	integer	null	Exclude videos newer than this many days ago. E.g. `7` = only show videos older than 1 week.
min_duration_minutes	integer	null	Minimum video duration in MINUTES (longform only). Hard floor of 8 minutes is enforced server-side — values below 8 are clamped up. Examples: 20 = 20 minutes, 60 = 1 hour, 90 = 1.5 hours. Common mistake: passing seconds — 1200 here means 1200 MINUTES (20 hours), not 20 minutes. For 20-minute videos pass 20, not 1200.
max_duration_minutes	integer	null	Maximum video duration in MINUTES (longform only). Must be >= 8; longform never returns videos shorter than 8 minutes. Examples: 60 = 1 hour, 120 = 2 hours. Common mistake: passing seconds — 3600 here means 3600 MINUTES (60 hours), not 1 hour. For 1-hour cap pass 60, not 3600.
min_views_24h	integer	null	Minimum channel views gained in last 24h (shorts only)
max_views_24h	integer	null	Maximum channel views gained in last 24h (shorts only)
min_views_48h	integer	null	Minimum channel views gained in last 48h (shorts only)
max_views_48h	integer	null	Maximum channel views gained in last 48h (shorts only)
min_outlier_score	number	null	Minimum outlier score. A video's `outlier_score` = its view count ÷ its channel's average views per video, so `2.5` means “video got 2.5× the channel's typical views.” Use this to surface videos over-performing their channel.
max_outlier_score	number	null	Maximum outlier score. Rarely needed — usually pair with `min_outlier_score`.
min_similarity	integer	null	Minimum similarity score (0–100). Only return videos with at least this similarity %. E.g. `55` = only show videos that are 55%+ similar.
include_youtube	boolean	false	Run a broader search alongside the curated query to cast a wider net. Adds ~1-3s latency. DEFAULT: False — leave off for normal viral discovery. SET TO TRUE when the user explicitly asks to ‘be exhaustive’ / ‘check everywhere’ / ‘broader search’, or the topic is obscure enough that curated coverage is likely thin. Silently ignored when ineligible.
category	string	null	Longform-only content-category filter. Only set when the user explicitly uses one of these keywords: `tutorial`, `educational`, `documentary`, `gaming`, `reviews`, `commentary`, `compilation`, `stories`, `interview`, `challenge videos`, `diy`, `speeches`, `memes`. Silently ignored on shorts.

TOOL find_channel_subjects

Subjects worth making next for a channel, taken from the channels most like it. Finds the closest channels by what they cover, reads what actually worked on them, groups the same topic written different ways, and removes what this channel has already made. Ranked by how many separate channels made a topic work, not by raw views.

Example prompt

"What should @CookTheMexicanWay make next?"

Parameter	Type	Default	Description
channel	string	required	A channel ID (`UCxxx`), `@handle`, bare handle, or channel URL.
sort	string	`proven`	`proven`: worked on several different channels, ranked by how many channels made it work. `best`: the single biggest win.
limit	integer	`40`	Rows back. Max 200.

TOOL find_channel_title_formats

Title formats worth stealing for a channel, taken from the channels most like it. A format is the title with its topic words replaced by slots, such as How To Make {thing} PUFF and Why It Happens. Same method as find_channel_subjects, ranked by how often the shape works across channels.

Example prompt

"Which title formats are working for channels like @CookTheMexicanWay?"

Parameter	Type	Default	Description
channel	string	required	A channel ID (`UCxxx`), `@handle`, bare handle, or channel URL.
sort	string	`proven`	`proven`: worked on several different channels, ranked by how many channels made it work. `best`: the single biggest win.
limit	integer	`40`	Rows back. Max 200.

Thumbnail Search

TOOL search_by_thumbnail

Search for longform videos by thumbnail similarity. Provide a YouTube video URL, an image URL, or a text description to find videos with visually similar thumbnails using similarity matching.

Example prompt

"Find videos with thumbnails similar to this image: https://i.ytimg.com/vi/abc123/maxresdefault.jpg"

Parameter	Type	Default	Description
image_url	string	null	URL of a thumbnail image to search with. Supports JPEG, PNG, WebP, and GIF.
video_url	string	null	YouTube video URL. Accepts watch, shorts, and youtu.be links.
q	string	null	Text description of the thumbnail style (e.g. “red arrow pointing at shocked face”).
limit	integer	50	Max results to return (1–50)
min_similarity	number	0.3	Minimum similarity threshold (0–1). Higher values return fewer but more visually similar results.
min_views	integer	null	Minimum video view count filter
max_views	integer	null	Maximum video view count filter
uploaded_within_days	integer	null	Only include videos uploaded within this many days. E.g. `7` = last week, `30` = last month.
uploaded_before_days	integer	null	Exclude videos newer than this many days ago. E.g. `7` = only show videos older than 1 week.

TOOL search_terminated_by_thumbnail

Search terminated/deleted channel videos by thumbnail similarity. Same as search_by_thumbnail but searches the terminated channels archive instead of active longform channels.

Example prompt

"Find terminated channel videos with thumbnails similar to this image: https://i.ytimg.com/vi/abc123/maxresdefault.jpg"

Parameter	Type	Default	Description
image_url	string	null	URL of a thumbnail image to search with. Supports JPEG, PNG, WebP, and GIF.
video_url	string	null	YouTube video URL. Accepts watch, shorts, and youtu.be links.
q	string	null	Text description of the thumbnail style (e.g. “red arrow pointing at shocked face”).
limit	integer	50	Max results to return (1–50)
min_similarity	number	0.3	Minimum similarity threshold (0–1). Higher values return fewer but more visually similar results.
min_views	integer	null	Minimum video view count filter
max_views	integer	null	Maximum video view count filter

Terminated Channels

Viral Videos

Thumbnail Search

Buy More Credits