Docs
Discovery Search
Terminated channels, viral videos, and thumbnail search tools.
Terminated Channels
search_terminated_channels
Search terminated/deleted YouTube channels. Returns channel metadata, growth metrics at time of termination, and top videos. Available on all plans.
| Parameter | Type | Default | Description |
|---|---|---|---|
| q | string | required | Search query. Matches channel titles and video titles. Comma-separated for multiple keywords. |
| 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
Example prompt
Search for terminated 'roblox' channels that had over 100k subscribers
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 (how many times more views a video has than its channel usually gets (long-form videos are compared with what the channel's own videos usually have at the same age; Shorts with the 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.
| 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 what the channel usually gets) |
| 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 = how many times more views it has than its channel usually gets (long-form videos are compared with what the channel's own videos usually have at the same age; Shorts with the 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. |
| niche | string | null | Longform-only niche filter, a key such as 'horror_paranormal', 'food_cooking', 'pets_animals', 'true_crime', 'history', 'gaming'. Unknown keys are ignored. DEFAULT: None. |
| sub_niche | string | null | A sub-niche inside niche (a video's sub_niche, e.g. tacos in food_cooking). Needs niche. |
| subject | string | null | Long-form only. Videos about this subject and its other wordings (a video's subject, or a trending_subjects name). |
| same_format_as | string | null | Long-form only. A video ID or URL; returns videos whose title uses the same format, each with format_band (same, close or loose), among the 1,500 closest title shapes. |
| 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. |
| monetized_only | boolean | false | Longform only: return only videos from monetized channels (1,000+ subscribers and ads detected on the channel). Channels never checked for monetization are left out. SET TO TRUE only when the user asks for monetized channels / channels that earn from ads / YPP channels. Ignored on shorts (no monetization data). DEFAULT: False. |
| languages | string | null | Shorts only. Comma-separated full names: English, Spanish, Portuguese, German, French, Japanese, Korean (e.g. Spanish,Portuguese). Defaults to English. Longform is English only and ignores it. |
Thumbnail Search
Example prompt
Find viral Shorts videos about cooking uploaded in the last 7 days with over 1 million views
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.
| 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. |
Example prompt
Find videos with thumbnails similar to this image: https://i.ytimg.com/vi/abc123/maxresdefault.jpg
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.
| 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 |
Find Channel
Example prompt
Find terminated channel videos with thumbnails similar to this image: https://i.ytimg.com/vi/abc123/maxresdefault.jpg
find_channel_from_screenshot
Identify which Shorts channel a screenshot belongs to, as the app's Find Channel page does. It reads the numbers off a YouTube Studio real-time analytics card or a channel page and matches them to Algrow's channels. Returns one match, or several with a confidence. Included in subscription. The screenshot needs a direct http(s) URL; an attached file has none.
| Parameter | Type | Default | Description |
|---|---|---|---|
| image_url | string | required | Direct http(s) URL of the screenshot |
| screenshot_type | string | realtime | realtime (Studio's real-time analytics card, best accuracy) or channel_about (the channel's page) |
Example prompt
Which channel is this? https://i.imgur.com/abc123.png