# Channel Research

Search and filter YouTube channels with similarity search and realtime growth metrics.

Search and filter YouTube channels programmatically. Uses similarity search combined with keyword matching, advanced filters, and realtime 24h/48h growth metrics. No credits required — available on all plans.

**Two channel databases:** `/api/channels/search` queries **Shorts channels** (vertical short-form content creators). `/api/longform-channels/search` queries **Longform channels** (standard YouTube video creators). Both support the same search and filter capabilities.

### `GET /api/channels/search`

Search Shorts channels with similarity search, keyword matching, and advanced filters. Returns channel metadata, realtime growth metrics (24h/48h), and recent videos. Results are paginated.

**Query Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| q | string | Required | — | Search query. Accepts a channel ID (e.g. `UCXx6GV...`), `@handle` (e.g. `@MrBeast`), a video URL (e.g. `https://youtube.com/shorts/...`, `https://youtu.be/...`), or a search term. Comma-separated for multiple keywords. Prefix with `-` to exclude (e.g. `gaming,-minecraft`). |
| languages | string | Optional | — | Filter by language. Comma-separated (e.g. `English,Spanish`) |
| sort | string | Optional | subs_desc | Sort field and direction. Format: `{field}_{asc\|desc}`. Fields: `subs`, `views`, `videos`, `age`, `added`, `views_24h`, `subs_24h`, `views_48h`, `similarity` |
| page | integer | Optional | 1 | Page number (1-indexed) |
| per_page | integer | Optional | 20 | Results per page (max 50) |
| min_subs | integer | Optional | — | Minimum subscriber count |
| max_subs | integer | Optional | — | Maximum subscriber count |
| min_avg_views | integer | Optional | — | Minimum average views per video |
| max_avg_views | integer | Optional | — | Maximum average views per video |
| min_age | integer | Optional | — | Minimum channel age in days |
| max_age | integer | Optional | — | Maximum channel age in days |
| min_uploads | integer | Optional | — | Minimum number of videos |
| max_uploads | integer | — | — | Maximum number of videos |
| min_views | integer | Optional | — | Minimum total view count |
| max_views | integer | Optional | — | Maximum total view count |
| min_views_24h | integer | Optional | — | Minimum views gained in last 24 hours |
| max_views_24h | integer | Optional | — | Maximum views gained in last 24 hours |
| min_views_48h | integer | Optional | — | Minimum views gained in last 48 hours |
| max_views_48h | integer | Optional | — | Maximum views gained in last 48 hours |
| min_similarity | integer | Optional | — | Minimum similarity score (0–100). Tightens the default similarity bar; only effective when `q` is a channel identifier or topic keyword and an embedding was generated. |

**Example Requests**

```
# Similarity search for gaming channels
curl "https://api.algrow.online/api/channels/search?q=gaming&languages=English&per_page=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter: young channels with high views, sorted by 24h growth
curl "https://api.algrow.online/api/channels/search?max_age=90&min_avg_views=500000&sort=views_24h_desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Exclude keywords: cooking channels but not baking
curl "https://api.algrow.online/api/channels/search?q=cooking,-baking&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response 200 200**

```
{
  "success": true,
  "page": 1,
  "per_page": 5,
  "count": 5,
  "channels": [
    {
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "channel_title": "Epic Gaming Shorts",
      "subscriber_count": 245000,
      "avg_views_per_video": 1850000,
      "total_videos": 47,
      "channel_age_days": 182,
      "view_count": 86950000,
      "primary_language": "English",
      "thumbnail_url": "https://yt3.ggpht.com/...",
      "view_increase_24h": 320000,
      "sub_increase_24h": 1200,
      "view_increase_48h": 580000,
      "similarity_score": 87,
      "recent_videos": [
        {
          "video_id": "dQw4w9WgXcQ",
          "title": "This game is INSANE",
          "view_count": 4200000,
          "upload_date": "2026-03-15",
          "thumbnail_url": "https://i.ytimg.com/vi/...",
          "url": "https://www.youtube.com/shorts/dQw4w9WgXcQ"
        }
      ]
    }
  ]
}
```

**Response Fields**

| Field | Type | Description |
| --- | --- | --- |
| channel_id | string | YouTube channel ID |
| channel_title | string | Channel name |
| subscriber_count | integer | Current subscriber count |
| avg_views_per_video | integer | Average views across all videos |
| total_videos | integer | Number of videos on the channel |
| channel_age_days | integer | Days since first upload |
| view_count | integer | Total channel views |
| primary_language | string | Detected content language |
| thumbnail_url | string | Channel profile picture URL |
| view_increase_24h | integer\|null | Views gained in last 24 hours |
| sub_increase_24h | integer\|null | Subscribers gained in last 24 hours |
| view_increase_48h | integer\|null | Views gained in last 48 hours |
| similarity_score | integer\|null | Similarity score (0–100) when using `q` search. Higher = more relevant. |
| recent_videos | array | Up to 6 most recent videos with `video_id`, `title`, `view_count`, `upload_date`, `thumbnail_url`, `url` |

200 Success 401 Auth failed 500 Server error

### `GET /api/longform-channels/search`

Search Longform channels (standard YouTube creators) with the same similarity search and filtering capabilities. Returns channel metadata, realtime growth metrics, and recent videos with duration info.

**Query Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| q | string | Optional | — | Search query. Accepts a channel ID, `@handle`, a video URL (e.g. `https://youtube.com/shorts/...`, `https://youtu.be/...`), or a search term. Comma-separated for multiple keywords, `-` to exclude. Omittable for browse mode when a `sells`/`monetization`/`faceless`/`gender`/`age` filter is present — combine with `sort=age_asc` for newest-first browsing. |
| languages | string | Optional | — | Filter by language (e.g. `English`) |
| sort | string | Optional | subs_desc | Sort field and direction. Fields: `subs`, `views`, `videos`, `age`, `total_views`, `added`, `views_24h`, `subs_24h`, `views_48h`, `similarity` |
| page | integer | Optional | 1 | Page number (1-indexed) |
| per_page | integer | Optional | 20 | Results per page (max 50) |
| min_subs | integer | Optional | — | Minimum subscriber count |
| max_subs | integer | Optional | — | Maximum subscriber count |
| min_avg_views | integer | Optional | — | Minimum average views per video |
| max_avg_views | integer | Optional | — | Maximum average views per video |
| min_age | integer | Optional | — | Minimum channel age in days |
| max_age | integer | Optional | — | Maximum channel age in days |
| min_uploads | integer | Optional | — | Minimum number of videos |
| max_uploads | integer | Optional | — | Maximum number of videos |
| min_duration | integer | Optional | — | Minimum average video duration in seconds |
| max_duration | integer | Optional | — | Maximum average video duration in seconds |
| monetized | string | Optional | — | Filter by monetization: `yes` or `no` |
| faceless | string | Optional | — | Filter by faceless classification: `yes` = only faceless channels (no on-camera host), `no` = only on-camera channels. Channels not yet classified are excluded from both filtered views. |
| min_views_24h | integer | Optional | — | Minimum views gained in last 24 hours |
| max_views_24h | integer | Optional | — | Maximum views gained in last 24 hours |
| min_views_48h | integer | Optional | — | Minimum views gained in last 48 hours |
| max_views_48h | integer | Optional | — | Maximum views gained in last 48 hours |
| categories | string | Optional | — | Comma-separated content categories. Lowercase, from: `tutorial`, `educational`, `documentary`, `gaming`, `reviews`, `commentary`, `compilation`, `stories`, `interview`, `challenge videos`, `diy`, `speeches`, `memes`. Unknown values return `400`. |
| min_similarity | integer | Optional | — | Minimum similarity score (0–100). Tightens the default 30% similarity floor; only effective when `q` is a channel identifier or topic keyword. Values below 30 are clamped to the default. |

**Example Requests**

```
# Search for finance channels under 1 year old
curl "https://api.algrow.online/api/longform-channels/search?q=finance&max_age=365&languages=English" \
  -H "Authorization: Bearer YOUR_API_KEY"

# High-growth longform channels sorted by 24h views
curl "https://api.algrow.online/api/longform-channels/search?min_views_24h=50000&sort=views_24h_desc&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Monetized channels with specific subscriber range
curl "https://api.algrow.online/api/longform-channels/search?min_subs=10000&max_subs=100000&monetized=yes" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Documentary channels only
curl "https://api.algrow.online/api/longform-channels/search?q=ancient+civilizations&categories=documentary" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response 200 200**

```
{
  "success": true,
  "page": 1,
  "per_page": 20,
  "count": 20,
  "channels": [
    {
      "id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "name": "Smart Money Moves",
      "subscriber_count": 52000,
      "avg_views_per_video": 185000,
      "total_videos": 34,
      "upload_day": 210,
      "view_count": 6290000,
      "primary_language": "English",
      "profile_picture": "https://yt3.ggpht.com/...",
      "monetized": true,
      "category": "documentary",
      "url": "https://youtube.com/@SmartMoneyMoves",
      "views_24h": 18500,
      "subs_24h": 340,
      "views_48h": 31200,
      "similarity_score": 92,
      "recent_videos": [
        {
          "video_id": "abc123xyz",
          "title": "How I Built a $10K/Month Side Income",
          "view_count": 420000,
          "upload_date": "2026-03-12",
          "thumbnail_url": "https://i.ytimg.com/vi/...",
          "url": "https://www.youtube.com/watch?v=abc123xyz",
          "duration": 845
        }
      ]
    }
  ]
}
```

**Longform vs Shorts response differences:** Longform channels use `id` and `name` instead of `channel_id` and `channel_title`. Videos include a `duration` field (in seconds). Longform also has `monetized`, `url`, and `upload_day` (days active) fields.

200 Success 401 Auth failed 500 Server error

### `GET /api/channel-trends`

Browse the top-growing channels ranked by recent view or subscriber deltas — the leaderboard that powers the Channel Trends page. Use this for browse-by-filter queries with no real topic to anchor a similarity search (e.g. “newest channels”, “biggest by subs”, “started in last 90 days”). Optionally pass `q` to narrow the leaderboard to a niche via embedding similarity.

**Query Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| content_type | string | Optional | shorts | `shorts` or `longform` — which index to rank. |
| metric | string | Optional | views | Sort metric. 24h: `views`, `subs`. Rolling 48h: `views_48h`, `subs_48h`. Rolling 7d: `views_7d`, `subs_7d`. `similarity` only when `q` is set. |
| q | string | Optional | — | Niche keyword or `@handle` to narrow the leaderboard. Comma-separated for multiple, `-` to exclude. Omit to browse the raw growth leaderboard. |
| page | integer | Optional | 1 | Page (1–20). |
| per_page | integer | Optional | 50 | Results per page (1–50). |
| languages | string | Optional | — | Comma-separated (e.g. `English,Spanish`). |
| min_subs / max_subs | integer | Optional | — | Subscriber count range. |
| min_avg_views / max_avg_views | integer | Optional | — | Average views per video range. |
| min_age / max_age | integer | Optional | — | Channel age in days since first upload. `max_age=60` = “started in last 2 months”. |
| min_videos / max_videos | integer | Optional | — | Video count range. |
| min_avg_duration / max_avg_duration | integer | Optional | — | Average video duration in seconds (longform only; floor of 420s/7min is enforced). |
| remove_low_quality | boolean | Optional | false | Exclude channels flagged low-quality. |
| remove_music | boolean | Optional | false | Exclude music channels (longform only). |
| faceless | string | Optional | — | `yes` = only faceless channels, `no` = only on-camera channels (longform only). Channels not yet classified are excluded from both filtered views. |

**Example Requests**

```
# Fastest-growing longform channels in the last 90 days
curl "https://api.algrow.online/api/channel-trends?content_type=longform&metric=views_7d&max_age=90&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Top growing Shorts channels in a specific niche
curl "https://api.algrow.online/api/channel-trends?q=cooking&metric=subs_48h&content_type=shorts" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

200 Success 400 Invalid metric/content_type 401 Auth failed 500 Server error