# YouTube Influencer Finder & Sponsor Outreach Leads (`egeusta/youtube-creator-sponsor-finder`) Actor

Find YouTube influencers for brand sponsorships using audience size, engagement, niche fit, sponsor history and public contact details.

- **URL**: https://apify.com/egeusta/youtube-creator-sponsor-finder.md
- **Developed by:** [Ege Usta](https://apify.com/egeusta) (community)
- **Categories:** Social media, Lead generation, Marketing
- **Stats:** 1 total users, 0 monthly users, 47.4% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

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

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

# Actor input Schema

## `queries` (type: `array`):

Niche keywords to search for creators, e.g. "home espresso", "budget travel".

## `channels` (type: `array`):

Optional direct channel references: UC… channel IDs, @handles, or youtube.com channel URLs.

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

Two-letter ISO country code used to bias the search (API mode).

## `relevanceLanguage` (type: `string`):

Optional BCP-47 language code (e.g. "en") to bias the search.

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

Creators with a known subscriber count below this are filtered out.

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

Creators with a known subscriber count above this are filtered out.

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

Upper bound on channels collected per query.

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

Global cap on unique creators emitted.

## `requestTimeoutSecs` (type: `integer`):

Per-request timeout.

## `maxApiPages` (type: `integer`):

Pagination / quota guard for the search step.

## `concurrency` (type: `integer`):

Parallel channel-detail requests.

## `includeContactInfo` (type: `boolean`):

Extract literally present emails, social profiles and links from the channel description / About links. No email guessing.

## `minVideosForFrequency` (type: `integer`):

Minimum analysed recent videos before an upload-frequency estimate is produced.

## `maxResponseBytes` (type: `integer`):

Hard ceiling on bytes read from a single response.

## Actor input object example

```json
{
  "queries": [],
  "channels": [],
  "regionCode": "US",
  "minSubscribers": 1000,
  "maxSubscribers": 5000000,
  "maxResultsPerQuery": 25,
  "maxTotalResults": 100,
  "requestTimeoutSecs": 30,
  "maxApiPages": 4,
  "concurrency": 4,
  "includeContactInfo": true,
  "minVideosForFrequency": 5,
  "maxResponseBytes": 5000000
}
```

# Actor output Schema

## `results` (type: `string`):

Structured YouTube creator profiles ranked for sponsorship outreach.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("egeusta/youtube-creator-sponsor-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("egeusta/youtube-creator-sponsor-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 '{}' |
apify call egeusta/youtube-creator-sponsor-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,egeusta/youtube-creator-sponsor-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/Kdkm53DMShnzxgXur/builds/ecaVofPTRtAC331qR/openapi.json