YouTube Creator Sponsor Finder

Build a sponsorship prospect list from YouTube. Find niche-relevant creators, rank influencer partnership opportunities, detect prior sponsorships and extract publicly listed business contacts for outreach.

Finds and ranks YouTube creators for sponsorship outreach using public channel, video and contact signals, with deterministic scoring.

Modes

Mode	Trigger	Signals
api	YOUTUBE_API_KEY environment variable is set	Full: search → channels → recent videos (subs, views, upload cadence, engagement).
public-pages	no API key	Parses ytInitialData from search + channel About pages. Fewer signals (no per-video stats).

The API key is read only from the environment, never from Actor input and never logged.

Input

Field	Type	Default	Notes
queries	string[]	[]	Niche keywords.
channels	string[]	[]	Seed channels: UC… IDs, @handles, or channel URLs. At least one of queries/channels is required.
regionCode	string	"US"	Two-letter ISO code (API mode search bias).
relevanceLanguage	string	—	BCP-47 code, e.g. en.
minSubscribers / maxSubscribers	integer	1000 / 5000000	Creators with a known count outside the range are dropped; unknown counts are kept and flagged subscriberCountKnown: false.
maxResultsPerQuery	integer	25	Channels per query.
maxTotalResults	integer	100	Global cap on unique creators.
requestTimeoutSecs	integer	30	Per-request timeout.
maxApiPages	integer	4	Search pagination / quota guard.
concurrency	integer	4	Parallel channel-detail requests.
includeContactInfo	boolean	true	Extract literally present emails / links only — no guessing.
minVideosForFrequency	integer	5	Minimum analysed videos before an upload-frequency estimate is produced.

Output

One type: "creator" item per unique channel (see .actor/dataset_schema.json): identity + channelUrl, subscriberCount / subscriberCountKnown, metrics (uploadFrequencyPerMonth, avgViewsPerVideo, medianViewsPerVideo, engagementRate, viewsToSubscribersRatio — each null when not measurable, never fabricated), sponsorHistory (detected, signals, confidence), contacts (emails, socialProfiles, otherLinks, hasBusinessContact), opportunityScore / readinessScore (0–100), creatorGrade (A–F), opportunityReasons, recommendedApproach, scoreBreakdown.

A SUMMARY record with mode, task / dedupe / filter counts, quota flag and failuresByReason is written to the key-value store.

Scoring

opportunityScore — weighted 0–1 signals: audience-fit (triangular around the geometric mid of the subscriber range), engagement (0.5–8 %), upload consistency (0.5–8 / month), views-to-subs efficiency, recency, monetization-openness (sponsor history), reachability. Missing data yields a low-neutral value — it never invents a strength. readinessScore re-weights toward reachability + sponsor history + recency. Grades use the shared 80/65/50/35 bands.

Safety

• No email guessing, no private-identity inference: only mailto: / visible addresses and links that literally appear in the channel description / About.
• All fetches go through the shared safeFetch / safeFetchJson (SSRF-guarded, redirect-capped, byte-limited, timeout cleared in finally).
• API errors that look like quota exhaustion set quotaExhausted and stop the affected task; other tasks continue. One failing task never aborts the run.
• Pagination is capped by maxApiPages; per-query results by maxResultsPerQuery.

Known limitations

• public-pages mode depends on ytInitialData layout; when YouTube changes it or serves a consent page the parser yields fewer / no creators and a warning, never a crash. Provide a YOUTUBE_API_KEY for reliable signals.
• Engagement and upload-frequency need per-video stats — only available in api mode (and only for public videos).
• YouTube hides channel business emails behind a CAPTCHA; those are never scraped. Email only appears here if the creator put it in their description.

Commands

npm ci                                       # monorepo root
npm run check -w youtube-creator-sponsor-finder
npm run smoke -w youtube-creator-sponsor-finder   # offline
npx apify validate-schema

Deployment

Not deployed here. apify push is intentionally not run — the lead engineer handles deployment.