# 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.

**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. |
| 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

### `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. |

## Thumbnail Search

### `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. |

### `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 |