Docs

Viral & Thumbnail Search

Find outlier videos and search channels by thumbnail image.

GET/api/viral-videos/search

Search for viral videos across Shorts and Longform channels, find videos similar to a specific video, or browse by filters alone. Filter by video views, channel size, growth metrics, upload recency, outlier score, and more. q, video_id, and video_url are all optional — omit them to browse by filters (e.g. “biggest outliers from the last 7 days”).

Query Parameters

Name	Type	Required	Default	Description
q	string	Optional	—	Search query. Matches video titles and channel names with similarity scoring. Also accepts `search` as an alias. Omit along with `video_id` / `video_url` to browse by filters alone.
video_id	string	Optional	—	YouTube video ID (e.g. `dQw4w9WgXcQ`). Finds videos similar to this video using title similarity.
content_type	string	Optional	shorts	Content type: `shorts` or `longform`
languages	string	Optional	English	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.
sort_by	string	Optional	views	Sort by: `views` (most viewed), `recent` (newest fetched), `upload_date` (newest uploaded), `similarity` (most similar — requires `q`/`video_id`/`video_url`; auto-selected when one is given), `outlier_score` (biggest over-performers — video views vs what the channel usually gets)
page	integer	Optional	1	Page number (1-indexed, max 20)
per_page	integer	Optional	20	Results per page (max 50)
min_video_views	integer	Optional	—	Minimum video view count
max_video_views	integer	Optional	—	Maximum video view count
min_subs	integer	Optional	—	Minimum channel subscriber count
max_subs	integer	Optional	—	Maximum channel subscriber count
min_uploads	integer	Optional	—	Minimum channel video count
max_uploads	integer	Optional	—	Maximum channel video count
min_channel_age	integer	Optional	—	Minimum channel age in days
max_channel_age	integer	Optional	—	Maximum channel age in days
min_upload_date	integer	Optional	—	Newest allowed upload (days ago, 0 = today)
max_upload_date	integer	Optional	—	Oldest allowed upload (days ago, e.g. 365 = 1 year)
min_duration	integer	Optional	—	Minimum video duration in minutes (longform only)
max_duration	integer	Optional	—	Maximum video duration in minutes (longform only)
min_views_24h	integer	Optional	—	Minimum channel views gained in last 24h (shorts only)
max_views_24h	integer	Optional	—	Maximum channel views gained in last 24h (shorts only)
min_views_48h	integer	Optional	—	Minimum channel views gained in last 48h (shorts only)
max_views_48h	integer	Optional	—	Maximum channel views gained in last 48h (shorts only)
min_outlier_score	float	Optional	—	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 to surface videos over-performing their channel.
max_outlier_score	float	Optional	—	Maximum outlier score. Rarely needed — usually pair with `min_outlier_score`.
sub_niche	string	Optional	—	A sub-niche inside `niche` (a video's `sub_niche`, e.g. `tacos` in `food_cooking`). Needs `niche`.
subject	string	Optional	—	Long-form only. Videos about this subject and its other wordings (a video's `subject`, or a name from `/api/trending/subjects`).
same_format_as	string	Optional	—	Long-form only. A video ID or URL: videos whose title uses the same format, among the 1,500 closest title shapes. Each comes with `format_band` and its title-shape `similarity_score`; the response has the seed's `title_format`. Other search inputs are ignored; `sort_by` is `similarity` (same, then close, then loose), `views`, `upload_date` or `outlier_score`. 404 when Algrow has not read that video's title format.

Response Fields (per video)

Field	Type	Description
video_id	string	YouTube video ID
title	string	Video title
channel_name	string	Channel name
channel_id	string	YouTube channel ID
view_count	integer	Total video views
outlier_score	float\|null	Outlier multiplier — how many times more views the 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). `4.2` = video got 4.2× the channel's typical views. `null` for brand-new uploads before the channel average is computed.
thumbnail_url	string	Video thumbnail URL
upload_date	string\|null	Upload date (ISO 8601)
url	string	Full YouTube URL
subscriber_count	integer	Channel subscriber count
duration	integer\|null	Video duration in seconds
view_increase_24h	integer\|null	Channel views gained in last 24h (shorts with realtime filters only)
view_increase_48h	integer\|null	Channel views gained in last 48h (shorts with realtime filters only)
similarity_score	integer\|null	Similarity score (0–100) when using search. Higher = more similar.
subject	string	Long-form, when known: what the video is about, a short lowercase phrase. Pass it back as `subject`.
title_format	string	Long-form, when known: the title with its topic words as slots, e.g. `Never Boil Your {thing} Again`.
niche	string	Long-form, when known: the video's niche key, e.g. `food_cooking`.
sub_niche	string	Long-form, when known: the shelf inside the niche, e.g. `beans`.
format_band	string	With `same_format_as`: `same` (the same title shape), `close` (a word or two apart) or `loose` (shares the idea).

Example Requests

# Find viral gaming Shorts with 1M+ views from small channels
curl "https://api.algrow.online/api/viral-videos/search?q=gaming&content_type=shorts&min_video_views=1000000&max_subs=50000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Longform fitness videos uploaded in last 7 days, sorted by views
curl "https://api.algrow.online/api/viral-videos/search?q=fitness+workout&content_type=longform&max_upload_date=7&sort_by=views" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Find videos similar to a specific video by ID
curl "https://api.algrow.online/api/viral-videos/search?video_id=dQw4w9WgXcQ&content_type=longform" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search for cooking videos from channels under 100k subs
curl "https://api.algrow.online/api/viral-videos/search?q=cooking&max_subs=100000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "content_type": "shorts",
  "page": 1,
  "per_page": 20,
  "count": 20,
  "videos": [
    {
      "video_id": "dQw4w9WgXcQ",
      "title": "This cooking hack changed everything",
      "channel_name": "Chef Secrets",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "view_count": 4200000,
      "outlier_score": 4.2,
      "thumbnail_url": "https://i.ytimg.com/vi/.../maxresdefault.jpg",
      "upload_date": "2026-03-15T00:00:00+00:00",
      "url": "https://www.youtube.com/shorts/dQw4w9WgXcQ",
      "subscriber_count": 32000,
      "duration": 58,
      "view_increase_24h": 180000,
      "view_increase_48h": 320000
    }
  ]
}

POST/api/thumbnail-search

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.

Request Body (JSON)

Name	Type	Required	Default	Description
image_url	string	One of three	—	URL of a thumbnail image to search with. Supports JPEG, PNG, WebP, and GIF formats.
video_url	string	One of three	—	YouTube video URL — automatically extracts its thumbnail. Accepts watch, shorts, and youtu.be links.
q	string	One of three	—	Text description of the thumbnail style to search for (e.g. “red arrow pointing at shocked face”, “before and after transformation”).
limit	integer	Optional	20	Maximum number of results to return (1–50)
min_similarity	float	Optional	0.3	Minimum similarity threshold (0–1). Higher values return fewer but more visually similar results.
min_views	integer	Optional	—	Minimum video view count filter

Response Fields (per video)

Field	Type	Description
video_id	string	YouTube video ID
title	string	Video title
channel_name	string	Channel name
channel_id	string	YouTube channel ID
view_count	integer	Total video views
thumbnail_url	string	Video thumbnail URL
upload_date	string\|null	Upload date (ISO 8601)
url	string	Full YouTube URL
duration	integer\|null	Video duration in seconds
subscriber_count	integer	Channel subscriber count
similarity_score	integer	Visual similarity score (0–100). Higher = more similar thumbnail.

Example Requests

# Search by image URL — find videos with similar thumbnails
curl -X POST "https://api.algrow.online/api/thumbnail-search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://i.ytimg.com/vi/abc123/maxresdefault.jpg", "limit": 10}'

# Search by text — describe the thumbnail style you're looking for
curl -X POST "https://api.algrow.online/api/thumbnail-search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "red arrow pointing at shocked face", "limit": 20}'

# Text search with filters — only high-view results
curl -X POST "https://api.algrow.online/api/thumbnail-search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "before and after transformation", "min_views": 100000, "min_similarity": 0.5}'

Response

{
  "success": true,
  "count": 10,
  "videos": [
    {
      "video_id": "abc123",
      "title": "How I Made $10k in 30 Days",
      "channel_name": "Finance Tips",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "view_count": 1500000,
      "thumbnail_url": "https://i.ytimg.com/vi/abc123/maxresdefault.jpg",
      "upload_date": "2026-03-20",
      "url": "https://www.youtube.com/watch?v=abc123",
      "duration": 612,
      "subscriber_count": 85000,
      "similarity_score": 78
    }
  ]
}

POST/api/terminated-thumbnail-search

Search terminated/deleted channel videos by thumbnail similarity. Same as /api/thumbnail-search but searches the terminated channels archive instead of active longform channels. Provide a YouTube video URL, an image URL, or a text description.

Request Body (JSON)

Name	Type	Required	Default	Description
image_url	string	One of three	—	URL of a thumbnail image to search with. Supports JPEG, PNG, WebP, and GIF formats.
video_url	string	One of three	—	YouTube video URL — automatically extracts its thumbnail. Accepts watch, shorts, and youtu.be links.
q	string	One of three	—	Text description of the thumbnail style to search for (e.g. “red arrow pointing at shocked face”, “before and after transformation”).
limit	integer	Optional	20	Maximum number of results to return (1–50)
min_similarity	float	Optional	0.3	Minimum similarity threshold (0–1). Higher values return fewer but more visually similar results.
min_views	integer	Optional	—	Minimum video view count filter
max_views	integer	Optional	—	Maximum video view count filter

Response Fields (per video)

Field	Type	Description
video_id	string	YouTube video ID
title	string	Video title
channel_name	string	Channel name
channel_id	string	YouTube channel ID
view_count	integer	Total video views
thumbnail_url	string	Video thumbnail URL
url	string	Full YouTube URL
subscriber_count	integer	Channel subscriber count
similarity_score	integer	Visual similarity score (0–100). Higher = more similar thumbnail.

Example Requests

# Search by image URL — find terminated videos with similar thumbnails
curl -X POST "https://api.algrow.online/api/terminated-thumbnail-search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://i.ytimg.com/vi/abc123/maxresdefault.jpg", "limit": 10}'

# Search by text — describe the thumbnail style
curl -X POST "https://api.algrow.online/api/terminated-thumbnail-search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "red arrow pointing at shocked face", "limit": 20}'

# Search by YouTube video URL
curl -X POST "https://api.algrow.online/api/terminated-thumbnail-search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://www.youtube.com/watch?v=abc123", "min_views": 50000}'

Response

{
  "success": true,
  "count": 10,
  "videos": [
    {
      "video_id": "abc123",
      "title": "How I Made $10k in 30 Days",
      "channel_name": "Finance Tips",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "view_count": 1500000,
      "thumbnail_url": "https://audio.algrow.online/thumbnails/abc123.jpg",
      "url": "https://www.youtube.com/watch?v=abc123",
      "subscriber_count": 85000,
      "similarity_score": 78
    }
  ]
}

POST/api/find-channel

Find which Shorts channel a screenshot belongs to. This is the analysis behind the app's Find Channel page. It reads the numbers off a YouTube Studio real-time analytics card, or off a channel page, and matches them to Algrow's channels. You get back one match, or several with a confidence. Included in your plan, no credits. Send a multipart screenshot file, or JSON with an image_url.

Request Body (multipart or JSON)

Name	Type	Required	Default	Description
screenshot	file	Conditional	—	The screenshot (multipart). Send this or `image_url`.
image_url	string	Conditional	—	A public http(s) URL of the screenshot (up to 25 MB).
type	string	Optional	realtime	`realtime` (Studio's real-time analytics card, best accuracy) or `channel_about` (the channel's page).

When several channels fit, channel_match is null and multiple_matches lists them, each with its own confidence. When none fit, success is false and error says why.

200 Success 400 Missing or invalid input 401 Auth failed

Example Request

curl -X POST "https://api.algrow.online/api/find-channel" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "type=realtime" \
-F "[email protected]"

Response200

{
  "success": true,
  "channel_match": {
    "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
    "channel_title": "Daily Cat Shorts",
    "subscriber_count": 48200
  },
  "multiple_matches": null,
  "single_match": true,
  "confidence": "high",
  "match_type": "realtime",
  "message": null,
  "extracted_data": { "success": true, … }
}

PreviousChannel Data NextYouTube Scraper