# Youtube Channel Finder (`coregent/youtube-channel-finder`) Actor

Fast YouTube channel discovery tool that extracts comprehensive channel information from YouTube searches and videos. Discover 5-20+ channels per search with 15 complete fields including profile, metrics, and metadata. No residential proxy required.

- **URL**: https://apify.com/coregent/youtube-channel-finder.md
- **Developed by:** [Delowar Munna](https://apify.com/coregent) (community)
- **Categories:** Developer tools, SEO tools, Social media
- **Stats:** 205 total users, 7 monthly users, 100.0% runs succeeded, 5 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.00 / 1,000 channel results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## YouTube Channel Finder ⚡

**Fast, low-cost YouTube channel discovery.** Find channels from **keywords, video URLs, or channel URLs** and export **29 complete channel fields** — profile, metrics, source attribution, and free derived analytics. Powered by the **official YouTube Data API v3** with a **browserless** discovery engine (no headless browser on the fast path).

![YouTube Channel Finder — fast, browserless YouTube channel discovery](https://raw.githubusercontent.com/coregentdevspace/youtube-channel-finder-assets/main/youtube-channel-finder-icon-image-thumbnail.png)

***

### 🚀 Key Features

- ⚡ **Browserless & fast**: keyword search, video URLs, and channel URLs are all resolved over plain HTTP — dozens of channels in seconds, no Chromium on the happy path.
- 🎯 **Enhanced discovery**: keyword search surfaces channels from **both** channel results **and** the creators behind video results (5–20+ per search).
- 🎬 **Video → channel**: drop in video URLs and get the channels behind them.
- 📊 **29 channel fields**: complete profile with subscriber/video/view counts, description, country, join date, keywords, verification, and type.
- 🧮 **Free derived analytics**: size tier, avg views/video, views/subscriber, and niche-fit score — computed from data already fetched, so they cost nothing extra.
- 🧭 **Source attribution**: every row records *why* it's in your results — which keyword or input found it, how, and its rank.
- 🔄 **Smart deduplication**: automatic by `ChannelId` within a run.
- 🎛️ **Niche presets**: one-click keyword sets for 10 common niches.
- 🌍 **Localization**: country and language targeting for discovery.
- 📦 **Bulk processing**: paste many URLs, upload a text file, or link a remote list.
- 📅 **Date & size filtering**: filter by join date and subscriber range, and sort to get a true top-N.
- 💪 **Resilient**: official API first, automatic fallbacks, browser only as a last resort.

> **Best for**: influencer marketing, partnership discovery, competitive analysis, market research, and creator scouting. Need **emails & social links**? Pair this with our **YouTube Channel Contacts & Social Links Scraper**.

***

### 🎯 At a Glance

| Feature | Value |
|---------|-------|
| **Speed** | Fast path: **dozens of channels in seconds** (browserless). Browser fallback: ~7–9s/channel |
| **Discovery** | **5–20+ channels per search** (vs 1–2 traditional) |
| **Inputs** | Keywords, niche presets, channel URLs, **video URLs**, bulk files |
| **Fields** | **29** comprehensive channel fields |
| **Method** | Official **YouTube Data API v3** + browserless HTTP discovery; browser fallback |
| **Deduplication** | Automatic by `ChannelId` |
| **Proxy** | Not required |

***

### 💡 Why This Scraper?

Most YouTube channel scrapers drive a headless browser for every channel — slow and expensive. YouTube Channel Finder is **browserless-first**:

| Metric | YouTube Channel Finder | Traditional Scrapers |
|--------|------------------------|----------------------|
| **Discovery per search** | 5–20+ channels | 1–2 channels |
| **Fast-path speed** | Dozens of channels in seconds | ~30–40s per channel |
| **Data source** | Official YouTube Data API v3 + HTTP | Browser scraping only |
| **Video URL → channel** | ✅ Browserless | ✅ Browser (slow) |
| **Field coverage** | 29 fields (incl. free derived analytics) | Varies |
| **Deduplication** | ✅ Automatic by ChannelId | ❌ Manual |
| **Proxy required** | ❌ No | Often yes |

**How it works:** keyword searches and video URLs are resolved to channel IDs over plain HTTP, then enriched in batches through the **official YouTube Data API v3**. If the API's daily free quota is exhausted, enrichment automatically falls back to a hosted API so runs keep working — the headless browser is only used as a final fallback for edge cases.

***

### 📋 Input Parameters

| Field | Key | Type | Default | Description |
|-------|-----|------|---------|-------------|
| **Search Keywords** | `searchQueries` | Array<string> | `[]` | Fuzzy keyword discovery — returns channels *related* to the terms (not one exact channel). Surfaces channels from both channel and video results. |
| **Channels & videos (exact match)** | `channelOrVideoInputs` | Array<string> | `[]` | Exact-match lookup. Channel **handle** (`@name`), **channel ID** (`UC…`), or **channel URL**; or a **video** ID / `watch?v=` URL / `youtu.be` / Shorts URL (returns the video's channel). One entry per line. |
| **Niche preset** | `nichePreset` | string | `""` | Ready-made keyword set for a common niche (AI & automation, SaaS, tech reviews, gaming, fitness, cooking, personal finance, education, beauty, travel). Adds 4 keywords to Search Keywords; yours take priority. |
| **Max channels per query** | `maxResultsPerQuery` | integer | `10` | Max channels per search keyword (1–50). |
| **Max total channels (whole run)** | `maxTotalResults` | integer | `0` | Run-level cap across all keywords + inputs combined; spend control. `0` = no limit. |
| **Min subscribers** | `minSubscribers` | integer | `0` | Keep only channels with ≥ this many subscribers. `0` = no minimum. |
| **Max subscribers** | `maxSubscribers` | integer | `0` | Keep only channels with ≤ this many subscribers. `0` = no maximum. |
| **Sort results by** | `sort` | string | `"relevance"` | `relevance` (discovery order), `subscribers` (highest first), or `date` (newest joined first). |
| **Country** | `regionCode` | string | `"US"` | ISO country code — US, GB, CA, AU, IN, DE, FR, JP, BR, MX. |
| **Language** | `language` | string | `"en"` | Language code — en, es, de, fr, pt, ja, hi, zh. |
| **From Date** | `dateFrom` | string (YYYY-MM-DD) | `""` | Filter by channel join date (Joined After). Optional. |
| **To Date** | `dateTo` | string (YYYY-MM-DD) | `""` | Filter by channel join date (Joined Before). Optional. |
| **Find channels similar to (paid extra)** | `similarToChannels` | Array<string> | `[]` | Opt-in. Seed channels (handle / ID / URL); returns channels YouTube associates with them via the related-video graph, ranked by recurrence. Up to `maxResultsPerQuery` per seed. Billed per similar channel (replaces the standard per-channel fee for those rows). |
| **Add activity metrics (paid extra)** | `includeActivityScore` | boolean | `false` | Opt-in. Adds upload cadence / consistency / activity fields (21–25 below). Billed per channel scored, on top of the result fee. Only channels actually returned are scored. |

> 💰 **Enrichment (paid extras)** — the last two fields above sit in their own **Enrichment** section in the Apify UI. Both are **OFF by default**: leave them alone and you pay only the standard per-channel result fee.

**Notes:**

- 🎯 **No required fields** — runs out of the box with sensible defaults.
- 🔎 **Two ways to find channels** — *Search Keywords* for fuzzy discovery; *Channels & videos* for exact lookups by handle, ID, or URL.
- 🎬 **Videos welcome** — paste a `watch?v=…` URL or a bare video ID and the actor returns the channel behind it.
- ✍️ **Bare inputs accepted** — `@handle`, `UC…` channel ID, or an 11-character video ID work without a full URL. (Write handles with the leading `@`; a bare 11-character token is treated as a video ID.)
- 🏆 **True top-N** — combine `sort` with `maxTotalResults` to get the *best* N, not the first N found. `sort=subscribers` + `maxTotalResults=10` returns the **10 most-subscribed** channels discovered, because sorting happens after filtering but **before** the cap.
- 🧮 **Free derived metrics** — size tier, avg views/video, views/subscriber and niche fit (fields 26–29) are computed from data already fetched, so they cost nothing extra and are always included.
- 📄 **Run summary** — every run writes a machine-readable `RUN_SUMMARY` record to the key-value store: counts by discovery method, filter/skip totals, API quota used, and billing. Kept out of the dataset so it never pollutes your results.
- ⚙️ Proxy, concurrency, and HTTP mode are tuned internally (no configuration needed).

***

### 📤 Output Schema

#### Comprehensive channel data — 29 fields (flat, spreadsheet-ready)

16 channel fields + 4 **source-attribution** + 5 **activity** (opt-in) + 4 **derived metrics** (free, always on).

| # | Field | Type | Description |
|---|-------|------|-------------|
| 1 | **ChannelId** | String | Unique YouTube channel ID (e.g., `UCiHVTkJtWSdc9N3h0nUGWLg`) |
| 2 | **ChannelName** | String | Display name |
| 3 | **ChannelHandle** | String | The `@handle` (e.g., `@n8n-io`) |
| 4 | **ChannelURL** | String | Canonical channel link |
| 5 | **ThumbnailURL** | String | Profile image / avatar URL |
| 6 | **BannerURL** | String | Channel banner / cover image URL (empty if the channel has none) |
| 7 | **Description** | String | Channel description / "About" text |
| 8 | **Country** | String | null | Listed country, if available |
| 9 | **JoinedDate** | String | null | Channel creation date (YYYY-MM-DD) |
| 10 | **SubscriberCount** | Integer | null | Total subscribers |
| 11 | **VideoCount** | Integer | null | Total videos uploaded |
| 12 | **TotalViews** | Integer | null | Lifetime view count |
| 13 | **Keywords** | Array<String> | Channel keywords / tags (if public) |
| 14 | **IsVerified** | Boolean | null | Verification badge. **`null` means unknown**, not unverified — the official Data API doesn’t expose the badge, so the fast path can’t determine it. `true`/`false` only when actually determined (fallback API or browser path). |
| 15 | **ChannelType** | String | null | e.g. "Creator", "Gaming", "Education" (if determinable) |
| 16 | **ScrapedAt** | String (ISO 8601) | Extraction timestamp |
| 17 | **SourceQuery** | String | The keyword that produced this channel (keyword search only; empty otherwise) |
| 18 | **SourceUrl** | String | The input token/URL that produced it — handle, channel ID/URL, or video (exact-match inputs; empty otherwise) |
| 19 | **DiscoveryMethod** | String | How it was found: `keyword_search`, `video`, `channel`, `handle`, or `similar` |
| 20 | **SearchRank** | Integer | null | 1-based rank within its keyword query (keyword search only; `null` otherwise) |

##### Activity metrics — fields 21–25 *(opt-in, paid extra: `includeActivityScore`)*

Empty/`null` unless you switch activity scoring on. Only channels actually returned are scored, so filtered-out rows never cost you anything.

| # | Field | Type | Description |
|---|-------|------|-------------|
| 21 | **LastUploadDate** | String (YYYY-MM-DD) | Date of the channel's most recent upload |
| 22 | **DaysSinceLastUpload** | Integer | null | Days elapsed since that upload — `0` means it posted today |
| 23 | **UploadsPerMonth** | Number | null | Average uploads per month across the recent sample |
| 24 | **UploadConsistency** | Integer | null | 0–100 regularity score — high means a steady, predictable cadence |
| 25 | **ActivityStatus** | String | `active`, `slowing`, `dormant`, or `inactive` |

##### Derived metrics — fields 26–29 *(free, always on)*

Computed from data already fetched — **no extra API call, no extra charge**.

| # | Field | Type | Description |
|---|-------|------|-------------|
| 26 | **SizeTier** | String | `nano` (<1K), `micro` (<100K), `mid` (<1M), `macro` (<10M), `mega` (10M+) |
| 27 | **AvgViewsPerVideo** | Integer | null | Lifetime views ÷ video count — a quick reach-per-upload read |
| 28 | **ViewsPerSubscriber** | Number | null | Lifetime views ÷ subscribers — indicates reach beyond the subscriber base |
| 29 | **NicheFit** | Integer | null | 0–100: share of your search terms found in the channel's own text. `null` only when the run has no keywords at all. **Use ≥67 as a reliable relevance filter** — lower scores can come from a single common word matching. |

> ℹ️ **Note on `IsVerified`**: the official YouTube Data API does not expose the verification badge, so on the fast path this field is **`null` (unknown)** rather than `false` — reporting `false` would wrongly assert that well-known verified channels are unverified. A real `true`/`false` appears only when the value is genuinely determined (fallback API or browser path).

> 🧭 **Source attribution**: fields 17–20 tell you *why* each channel is in your results — which keyword or input produced it, how, and (for keyword search) its rank. A channel found via multiple inputs is attributed to the first one that discovered it.

***

### 📊 Output Examples

#### Results tab — table view

![YouTube Channel Finder output — Results tab, 29 channel fields in table view](https://raw.githubusercontent.com/coregentdevspace/youtube-channel-finder-assets/main/youtube-channel-finder-output-results.png)

#### Results tab — JSON view

One complete record, exactly as returned (fitness keyword search, activity scoring enabled):

```json
{
  "ChannelId": "UCeJFgNahi--FKs0oJyeRDEw",
  "ChannelName": "Hybrid Calisthenics",
  "ChannelHandle": "@hybridcalisthenics",
  "ChannelURL": "https://www.youtube.com/@hybridcalisthenics",
  "ThumbnailURL": "https://yt3.ggpht.com/ytc/AIdro_lHDTeNbNPLCIuChuhtXjCMZ6S6UQ6nPhDKewcrZj5i1Q=s800-c-k-c0x00ffffff-no-rj",
  "BannerURL": "https://yt3.googleusercontent.com/jb3D1zUmb8cUAaWd8xI7nb_SREoy0MH3WOyOhAOfOmYvGa7qRvczaGV-HLQlBuHAVf1otoNG3Vc",
  "Description": "Hey everyone! My name is Hampton and my brand is Hybrid Calisthenics...\n\nMy goal is to help people cultivate long-term fitness and health with calisthenics.\n",
  "Country": "US",
  "JoinedDate": "2020-01-03",
  "SubscriberCount": 4460000,
  "VideoCount": 781,
  "TotalViews": 775039734,
  "Keywords": [
    "calisthenics",
    "fitness",
    "health",
    "home workout",
    "strength",
    "flexibility",
    "mobility",
    "building muscle"
  ],
  "IsVerified": null,
  "ChannelType": "Lifestyle",
  "ScrapedAt": "2026-07-23T13:08:59.480Z",
  "SourceQuery": "strength training tips",
  "SourceUrl": "",
  "DiscoveryMethod": "keyword_search",
  "SearchRank": 17,
  "LastUploadDate": "2026-07-23",
  "DaysSinceLastUpload": 0,
  "UploadsPerMonth": 21.1,
  "UploadConsistency": 41,
  "ActivityStatus": "active",
  "SizeTier": "macro",
  "AvgViewsPerVideo": 992368,
  "ViewsPerSubscriber": 173.8,
  "NicheFit": 67
}
```

*(`Description` and `Keywords` abbreviated for readability — the actual record returns them in full.)*

**Output benefits:**

- 🎯 **Flat & clean** — numeric counts, ISO dates, typed fields; imports straight into Google Sheets / Excel / BI.
- 📐 **Uniform rows** — every record carries all 29 keys whether or not a value was found, so CSV and Excel exports never come out ragged.
- ⚡ **Fast path** — official API enrichment in batches, no per-channel browser load.
- 💼 **Business-ready** — everything needed for partnerships, competitive analysis, and market research.
- 🚀 **Enhanced discovery** — 5–20+ channels per search.

***

### 🎬 Quick Start

#### Example 1: Keyword search

```json
{
  "searchQueries": ["n8n"],
  "maxResultsPerQuery": 20,
  "regionCode": "US",
  "language": "en"
}
```

#### Example 2: Videos (returns the channels behind the videos)

```json
{
  "channelOrVideoInputs": [
    "https://www.youtube.com/watch?v=7Sx0o-41r2k",
    "https://youtu.be/5oAnKSCP4do",
    "QJBP2uy8LcU"
  ]
}
```

#### Example 3: Exact channel lookup (handle, ID, or URL)

```json
{
  "channelOrVideoInputs": [
    "@mkbhd",
    "UCX6OQ3DkcsbYNE6H8uQQuVA",
    "https://www.youtube.com/@n8n-io",
    "https://www.youtube.com/channel/UCiHVTkJtWSdc9N3h0nUGWLg"
  ]
}
```

#### Example 4: Niche preset — a whole niche in one click

```json
{
  "nichePreset": "fitness",
  "maxResultsPerQuery": 20,
  "regionCode": "US",
  "language": "en"
}
```

#### Example 5: True top-N — the 25 biggest channels in a niche

Sorting happens **after** filtering but **before** the cap, so this returns the 25 most-subscribed channels discovered — not the first 25 found.

```json
{
  "nichePreset": "cooking",
  "maxResultsPerQuery": 30,
  "minSubscribers": 50000,
  "sort": "subscribers",
  "maxTotalResults": 25
}
```

#### Example 6: With the paid extras switched on

Both extras are **off by default**. This run adds activity metrics to every returned channel and expands the list with channels similar to two seeds.

```json
{
  "searchQueries": ["home workout routine"],
  "similarToChannels": ["@hybridcalisthenics", "@madfit"],
  "includeActivityScore": true,
  "maxResultsPerQuery": 20
}
```

***

### 💪 Performance & Reliability

#### Architecture (browserless-first)

- **Discovery** — keyword searches resolve to channel IDs over HTTP; video URLs resolve to their channel by fetching the watch page (no browser).
- **Enrichment** — channel IDs are enriched in batches through the **official YouTube Data API v3** (14 of the 16 core fields; the rest are generated locally at no cost).
- **Automatic fallback** — if the API's daily free quota is exhausted, a hosted API enriches channels instead, so runs don't stall.
- **Browser last resort** — the headless browser is used only for edge cases the HTTP paths can't handle.
- **Deduplication** — automatic by `ChannelId`.

#### Throughput

The browserless fast path processes **many channels in seconds** (discovery + batched enrichment). When the browser fallback is used, expect ~7–9s per channel.

***

### 📚 Use Cases

- **Influencer marketing** — find creators by niche with subscriber/verification data.
- **Partnership discovery** — build target lists with complete channel profiles.
- **Competitive analysis** — compare competitor channels by subscribers, output, and views.
- **Market research** — analyze 100–200+ channels by country, type, and niche.
- **Creator scouting** — surface emerging channels with growth indicators.
- **Channel databases** — assemble structured, spreadsheet-ready channel records.

***

### 💲 Pricing

**Pay only for results.** No monthly rental, **no per-run fee, and no charge at all on a run that returns nothing.** You're billed per **unique channel** returned — that's it. Two optional extras bill only if you switch them on.

| Event | Charged when |
|-------|--------------|
| **Channel result** | Once per **unique** channel written to the dataset |
| **Similar channel** *(opt-in)* | Once per channel found via `similarToChannels` — **replaces** the standard channel fee for those rows, never charged on top of it |
| **Activity score** *(opt-in)* | Once per channel **successfully** scored when `includeActivityScore` is on |

| Run size | Events billed |
|----------|---------------|
| 0 channels (nothing found) | **nothing — the run is free** |
| 10 channels | 10 channel results |
| 1,000 channels | 1,000 channel results |

- **Default runs cost the standard rate.** Leave both extras off — as they ship — and you pay only the per-channel fee.
- **Not charged:** empty runs, duplicate channels (deduped within a run), rows filtered out by your date/subscriber/cap settings, failed activity scores, and failed / not-found lookups.
- **Free of charge:** the four derived metrics (fields 26–29) are computed from data already fetched — no extra event, no extra cost.
- **Live rates:** see the **Pricing** tab on this actor's page for the current per-event prices. *(This README deliberately doesn't quote figures — the Pricing tab is always current.)*

> 💡 Use **`maxTotalResults`** to cap the number of channels — and therefore the cost — on large multi-keyword or bulk runs. Filtering and sorting are applied **before** the cap and before any paid scoring, so you never pay for rows you don't receive.

***

### ❓ FAQ

**Q: How many channels can I discover per search?**
A: **5–20+ per search** — the actor extracts both explicit channel results and the creators behind video results.

**Q: Does it scrape every video from a channel?**
A: No. This actor **finds and profiles channels**. It does not download a channel's full video list.

**Q: How is this different from a "YouTube Channel Video" / video scraper?**
A: Many similarly-named actors scrape **videos**. This one returns **channels** — one clean profile row per channel (subscribers, views, country, join date, keywords, verification, type), not a list of videos. Use it to *find and shortlist creators*; if you then need each channel's videos or their emails/social links, pair it with the matching video or **Contacts & Social Links** scraper.

**Q: Can I cap the total number of results (and the cost)?**
A: Yes — set **`maxTotalResults`** to cap the number of channels returned across *all* keywords and inputs combined (0 = no limit). The cap is applied before enrichment, so it also controls spend on large multi-keyword or bulk runs. `maxResultsPerQuery` still caps each individual keyword.

**Q: Why is a given channel in my results — which input found it?**
A: Every record includes **source attribution** — `SourceQuery` (the keyword), `SourceUrl` (the input token/URL), `DiscoveryMethod` (`keyword_search`/`video`/`channel`/`handle`), and `SearchRank` (rank within its keyword). A channel found via multiple inputs is attributed to the first one that discovered it.

**Q: How does it stay fast and cheap?**
A: It's **browserless-first** — keyword searches and video URLs resolve over plain HTTP, then channels are enriched in batches via the **official YouTube Data API v3**. A headless browser is only a last-resort fallback, which keeps runs fast and low-cost.

**Q: Can I pass video URLs?**
A: Yes — paste `watch?v=…` links (or a mix of channel and video URLs) and the actor returns the channels behind them.

**Q: Can I filter by channel join date?**
A: Yes — use `dateFrom` / `dateTo` (YYYY-MM-DD). Leave empty to include all channels.

**Q: Can I target a country / language?**
A: Yes — set `regionCode` and `language`. Each channel's own country is also extracted when available.

**Q: I need creator emails and social links.**
A: Use our companion actor, **YouTube Channel Contacts & Social Links Scraper**, which adds email and categorized social links.

***

### 🛠️ Technologies

- **Discovery**: browserless HTTP resolution of keyword searches and video URLs (YouTube `ytInitialData`).
- **Enrichment**: official **YouTube Data API v3** (`channels.list`, batched) with an automatic hosted-API fallback.
- **Fallback engine**: Puppeteer (headless Chrome) + Crawlee — used only when HTTP paths can't complete.
- **Runtime**: Node.js 18+.
- **Deduplication**: `ChannelId` tracking across all sources.

***

### 📋 Best Practices

1. **Start small** — test with `maxResultsPerQuery: 10` to see 5–20+ channels per search.
2. **Use broad keywords** — they discover more channels via dual extraction.
3. **Mix inputs** — combine keywords, channel URLs, and video URLs in one run.
4. **Filter by date** — use `dateFrom` / `dateTo` to target newer or older channels.
5. **Export** — JSON / CSV / Excel to Sheets, S3, or your CRM.

***

### 📜 Changelog

**v2.5 — Discovery & analytics update (July 2026)**

- 🧮 **Free derived metrics** — size tier, avg views/video, views/subscriber, and a niche-fit score on every row at no extra cost.
- 🧭 **Source attribution** — every channel records which keyword or input found it, how, and its rank.
- 🎛️ **Niche presets** — ready-made keyword sets for 10 common niches.
- 🔗 **Similar-channel discovery** (opt-in) — expand a seed channel into its related-channel neighbourhood.
- 📈 **Activity metrics** (opt-in) — upload cadence, consistency, and an active/slowing/dormant/inactive status.
- 🎚️ **Subscriber filters + true top-N sorting** — sort is applied before the run cap, so you get the best N, not the first N.
- 📄 **Run summary** — a machine-readable `RUN_SUMMARY` record in the key-value store, kept out of your dataset.

**v2.5 — Browserless update (July 2026)**

- ⚡ **Browserless-first architecture** — keyword search, video URLs, and channel URLs resolved over HTTP; headless browser only as a last-resort fallback.
- 🎬 **Video URLs resolved browserlessly** (previously required a browser).
- 🔁 **Automatic enrichment fallback** when the YouTube Data API daily quota is exhausted — runs keep working.
- 🏎️ **Major speed & cost improvement** on the fast path.
- 🧹 Reliability fixes (About-page navigation, join-date accuracy).

**v2.5 — YouTube Data API v3 (Feb 2026)**

- Replaced the previous hybrid method with the **official YouTube Data API v3** (13/15 fields from the API).
- Removed the legacy third-party extraction API.

**Earlier (2025)**

- Enhanced discovery (channels from channel + video results, YouTube channel filter), 15-field schema, hybrid HTTP/Puppeteer mode.

***

### 🤝 Compliance

- Collects only **public** YouTube channel data.
- Uses the official YouTube Data API v3 within its terms.
- Intended for legitimate channel discovery, influencer research, and business intelligence.
- Users are responsible for compliance with applicable laws in their jurisdiction.

***

### 💬 Support

- **Issues / feature requests**: via GitHub or Apify support.
- **Documentation**: see the `/docs` folder for the PRD and guides.

***

**Built with ❤️ for fast, low-cost channel discovery.**

# Actor input Schema

## `searchQueries` (type: `array`):

Keyword search to discover relevant YouTube channels. This is a fuzzy search — it returns channels related to the terms, not one specific channel. To look up an exact channel or video, use the Channels & Videos field below instead.

## `nichePreset` (type: `string`):

Pick a ready-made set of search keywords instead of writing your own. The preset's keywords are ADDED to Search Keywords above (yours take priority; duplicates are dropped). Each preset adds 4 queries, so keep an eye on 'Max total channels' for spend control.

## `maxResultsPerQuery` (type: `integer`):

Maximum number of channels to discover per search keyword. Each search will return up to this many unique channels.

## `maxTotalResults` (type: `integer`):

Optional overall cap on the number of channels returned across ALL keywords and inputs combined — a run-level spend control. 0 = no limit.

## `minSubscribers` (type: `integer`):

Only return channels with at least this many subscribers. 0 = no minimum. Channels that hide their subscriber count are kept.

## `maxSubscribers` (type: `integer`):

Only return channels with at most this many subscribers. 0 = no maximum. Channels that hide their subscriber count are kept.

## `sort` (type: `string`):

Order of the returned channels. 'Relevance' keeps discovery order. 'Subscribers' and 'Join date' sort AFTER filtering but BEFORE the total cap — so combined with 'Max total channels' you get a true top-N (e.g. the 10 most-subscribed channels found), not just the first 10 found then sorted.

## `regionCode` (type: `string`):

YouTube search region - affects which results appear, not channel location (ISO 3166-1 alpha-2)

## `language` (type: `string`):

Preferred language (IETF BCP-47).

## `dateFrom` (type: `string`):

Filter channels that joined YouTube after this date (optional). Leave empty to include all channels regardless of join date.

## `dateTo` (type: `string`):

Filter channels that joined YouTube before this date (optional). Leave empty to include all channels regardless of join date.

## `channelOrVideoInputs` (type: `array`):

Exact-match lookup. Add YouTube channels — as a handle (@name), channel ID (UC…), or channel URL — and/or videos — as a video ID, watch URL, youtu.be link, or Shorts URL. Each entry resolves to the exact channel(s). One entry per line. Tip: write bare handles with the leading @; a bare 11-character token is treated as a video ID.

## `similarToChannels` (type: `array`):

Opt-in discovery. Give one or more seed channels (handle @name, channel ID UC…, or channel URL) and the actor returns channels YouTube itself associates with them, found via the related-video graph and ranked by how often they recur. Up to 'Max channels per search term' per seed. Billed per similar channel returned (these replace, not add to, the standard per-channel fee).

## `includeActivityScore` (type: `boolean`):

Opt-in enrichment. Adds LastUploadDate, DaysSinceLastUpload, UploadsPerMonth, UploadConsistency (0-100) and ActivityStatus (active/slowing/dormant/inactive) to each returned channel. Billed per channel scored, on top of the per-channel result fee — only channels actually returned are scored. Leave off for the standard price.

## Actor input object example

```json
{
  "searchQueries": [
    "n8n"
  ],
  "nichePreset": "",
  "maxResultsPerQuery": 10,
  "maxTotalResults": 0,
  "minSubscribers": 0,
  "maxSubscribers": 0,
  "sort": "relevance",
  "regionCode": "US",
  "language": "en",
  "dateFrom": "",
  "dateTo": "",
  "channelOrVideoInputs": [
    "https://www.youtube.com/watch?v=7Sx0o-41r2k",
    "@MrBeast",
    "UCX6OQ3DkcsbYNE6H8uQQuVA"
  ],
  "similarToChannels": [],
  "includeActivityScore": false
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchQueries": [
        "n8n"
    ],
    "channelOrVideoInputs": [
        "https://www.youtube.com/watch?v=7Sx0o-41r2k",
        "@MrBeast",
        "UCX6OQ3DkcsbYNE6H8uQQuVA"
    ],
    "similarToChannels": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("coregent/youtube-channel-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchQueries": ["n8n"],
    "channelOrVideoInputs": [
        "https://www.youtube.com/watch?v=7Sx0o-41r2k",
        "@MrBeast",
        "UCX6OQ3DkcsbYNE6H8uQQuVA",
    ],
    "similarToChannels": [],
}

# Run the Actor and wait for it to finish
run = client.actor("coregent/youtube-channel-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchQueries": [
    "n8n"
  ],
  "channelOrVideoInputs": [
    "https://www.youtube.com/watch?v=7Sx0o-41r2k",
    "@MrBeast",
    "UCX6OQ3DkcsbYNE6H8uQQuVA"
  ],
  "similarToChannels": []
}' |
apify call coregent/youtube-channel-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,coregent/youtube-channel-finder"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/6KiBCoMjYTnXrvOx5/builds/8YKkg7mFzeNQotxvA/openapi.json