# Influencer Finder: Score Your Creator List Against a Brief (`ntriqpro/influencer-fit-finder`) Actor

Bring your creator list and score it against your campaign brief: a dataset or CSV from any YouTube, Instagram or TikTok scraper (Instagram/TikTok need bio and post data). Per creator a verdict with the quoted sentence, AI fit review (paid), ranked shortlist. Free: 1 creator in full.

- **URL**: https://apify.com/ntriqpro/influencer-fit-finder.md
- **Developed by:** [daehwan kim](https://apify.com/ntriqpro) (community)
- **Categories:** Social media, Lead generation, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $15.60 / 1,000 ai fit revieweds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Influencer Finder: Score Your Creator List Against a Brief

**Bring your creator list and score it against your campaign brief.** This Actor does not search for creators — you bring the list: a dataset or CSV from a YouTube, Instagram or TikTok scraper, or your own spreadsheet. **Instagram and TikTok creators need their bio and posts in that data** (from a profile or post scraper); a bare Instagram or TikTok handle comes back `unclear`. YouTube channels typed in are read from their public About page. Then, per creator, **one row with a verdict against your brief and the exact sentence it rests on**, an AI fit review with the audience and risk flags (paid plans), and **one ranked shortlist** of the best fits with the reasons the rest were excluded.

### Free plan vs paid plans

| | Free plan | Paid plans |
|---|---|---|
| Creators scored per run | the first **1** in full; the rest as counts only (how many strong or possible, weak, excluded, unclear — not who) | up to **5,000** in full (`maxCreators`, default 500) |
| Rule verdict: `mustHave` keywords, `exclude` keywords, follower range — each match with the quoted sentence and where it is (bio, post n) | ✅ | ✅ |
| **AI fit verdict** vs your brief: strong / possible / weak / unclear, quotes from the creator's own text, stated audience, topics, risk flags | 🔒 locked — the preview row counts how many creators a paid run could send | ✅ up to `aiMaxItems` (default 200) |
| **Ranked shortlist row**: up to N strong/possible fits + why the others were excluded | 🔒 locked — the preview row counts the candidates by the rules | ✅ one per run |
| Contact fields you brought in (e-mail, phone, website) | carried over as given | carried over as given |

The free run ends with a `free-plan-preview` row with numbers counted in that run, each saying what it counts: the creators read, the ones a paid run takes (`maxCreators`), the rule counts over them, how many could go to the AI review (requests — a review that fails our checks is not a verdict and is not charged), the shortlist candidates and the most it lists, and an estimate of this Actor's events for a paid run (your Apify plan and the scrapers that made your data are not in it). The free plan uses your own Apify credits for its run-start fee and the one creator it judges.

#### What the paid AI layer adds — a fixed example

*Illustrative only: made-up sample data, not one of your creators and not a measured model answer. Every free run's preview row carries the same example (`example`).*

```json
{
  "handle": "trailcook.example",
  "ruleFit": { "verdict": "possible", "reasons": [{ "term": "camping", "quote": "Camping recipes for two-day hikes.", "source": "bio" }], "mustHaveMissing": ["tent"] },
  "fit": { "status": "reviewed", "fit": "strong",
    "reasons": [{ "quote": "Testing a new backpacking stove on the ridge", "why": "Reviews the stove category the brief names." }],
    "audience": "beginner backpackers", "topics": ["camp cooking", "backpacking"], "flags": ["sponsorship-mentioned"] }
}
```

The rules found one keyword (`possible`); the AI review read a post the keywords missed and rated it `strong`, with the quote, the stated audience and a sponsorship flag.

#### Paid-plan discounts

| Event | FREE | BRONZE (−20%) | SILVER (−35%) | GOLD and above (−48%) |
|---|---:|---:|---:|---:|
| Run started (once per run) | $0.005 | $0.004 | $0.00325 | $0.0026 |
| Creator checked (rule verdict, one per creator) | $0.005 | $0.004 | $0.00325 | $0.0026 |
| AI fit reviewed (one per verdict that passed our checks) | $0.03 | $0.024 | $0.0195 | $0.0156 |
| Shortlist ranked (one per run) | $0.10 | $0.08 | $0.065 | $0.052 |
| Source access checked (a typed YouTube channel YouTube refused, 403/429 — instead of a creator check) | $0.005 | $0.004 | $0.00325 | $0.0026 |

The store card shows **AI fit reviewed** (the primary event): it is charged per AI verdict **on top of** the creator check, the run start and the shortlist. Example: 100 creators on BRONZE with an AI verdict for each = $0.004 + 100 × $0.004 + 100 × $0.024 + $0.08 = **$2.884** (this Actor's events; the scraper runs that made your list are separate). Your run's maximum charge is always respected: when it is reached the run stops cleanly (SUCCEEDED) and says what was left out.

### What you give it

- **`datasetIds`** — datasets of other runs on your account (any scraper). Field names of common scrapers are read as they come:
  - YouTube: `channelUrl`, `channelId`, `handle`, `title` / `channelName`, `description`, `subscriberCount` / `subscribers`, `email` / `emails` (our [YouTube Channel Email Finder](https://apify.com/ntriqpro/youtube-channel-email-finder) and YouTube Channel Monitor, and the common YouTube e-mail scrapers);
  - Instagram: `username`, `fullName`, `biography`, `followersCount`, `latestPosts[].caption`, `businessEmail`, `externalUrl` (Apify's Instagram Profile Scraper), and post rows with `ownerUsername` + `caption`;
  - TikTok: `authorMeta.name`, `authorMeta.signature`, `authorMeta.fans`, `text`, `hashtags` (one row per video — the rows of one creator are merged).
- **`csvUrls`** — public CSV or JSON files with the same columns (Apify's flattened export headers like `authorMeta/name` are read).
- **`creators`** — profiles typed in: `https://www.youtube.com/@name`, `instagram.com/name`, `tiktok.com/@name`, `@handle`, `instagram:name`, `tiktok:name`. For **YouTube** channels typed here the public About page is read once (no login). For Instagram and TikTok entries typed here only the handle is known, so their verdict is usually `unclear` — bring a dataset with their bio and posts.
- **`brief`** — one or two sentences about the campaign. **`mustHave`** and **`exclude`** keyword lists, **`minFollowers`** / **`maxFollowers`**.

The same creator from several sources is scored and charged once.

### What you get

One `creator` row per creator (an example on made-up data — the fields are those of a real row):

```json
{
  "recordType": "creator",
  "platform": "instagram",
  "handle": "trailcook.example",
  "name": "Trail Cook",
  "followers": 48200,
  "verdict": "strong",
  "verdictSource": "ai",
  "ruleFit": {
    "verdict": "possible",
    "score": 3,
    "reasons": [{ "term": "camping", "quote": "Camping recipes for two-day hikes.", "source": "bio" }],
    "mustHaveFound": ["camping"],
    "mustHaveMissing": ["tent"],
    "excludeHits": [],
    "followerRange": "in",
    "excluded": false
  },
  "fit": {
    "status": "reviewed",
    "fit": "strong",
    "reasons": [{ "quote": "Testing a new backpacking stove on the ridge", "why": "Reviews the stove category the brief names." }],
    "audience": "beginner backpackers",
    "audienceEvidence": "for beginner backpackers",
    "topics": ["camp cooking", "backpacking"],
    "flags": ["sponsorship-mentioned"],
    "model": "claude-haiku-5-5"
  },
  "topics": ["camp cooking", "backpacking", "camping"],
  "riskFlags": ["ai:sponsorship-mentioned"],
  "contacts": { "emails": ["hello@trailcook.example"], "phone": null, "website": null },
  "plan": "paid",
  "billedEvents": ["creator-checked", "fit-reviewed"]
}
```

One `shortlist` row per run (paid plans): `verdictCounts`, `top` (rank, handle, verdict, top reason, risk flags), `excludedCount`, `exclusionReasons` (for example `exclude-term:casino`, `followers-below-min`, `ai:exclusion-match`) and `notFitReasons`.

Plus notice rows (never charged) and one `limits` row with the run's own report. A run that uses the AI review writes one `ai-life` notice before its first model request (one more after each restart of the run): it is a record for the run's own restart checks, not a result.

### How the verdicts are made

- **Rules (every plan, no AI):** your keywords and the topic words of your brief are matched against the creator's own public text. `strong` = every `mustHave` found (or four or more brief topics without `mustHave`), `possible` = some, `weak` = none or excluded, `unclear` = no public text in your data. Every match comes back with the sentence it was found in, as written.
- **AI (paid plans, beta):** the creator's public text and your brief go to Anthropic's API (claude-haiku-5-5). The answer is checked before it is used: every quote must be in the creator's text letter for letter, the audience must be quoted, an exclusion flag must be quoted, and no number may appear that is in neither the text nor your brief. An answer that fails is thrown away and **not charged**; the row keeps the rule verdict. Creators without public text and creators your rules already exclude are not sent.
- **Privacy:** with the AI review on, the creators' public text and your brief are sent to **Anthropic's API (United States)**. E-mail and web addresses are removed from the text first, and no contact field is ever sent. Turn `aiFit` off to keep everything on Apify.

### What is charged, and what is not

- **Charged:** the run-start fee once per run, when the input checks passed and before the sources are read — it pays for reading and merging what you gave, also when it holds no creator or a source cannot be read. Every creator row the rules scored — also `weak` and `unclear` ones (the verdict is the product), and a YouTube channel YouTube answers does not exist. A typed YouTube channel whose lookup YouTube refused (HTTP 403/429): a row with `accessRefused: true` and no verdict, charged once as a source access check instead. AI verdicts that passed the checks. The shortlist row.
- **Not charged:** an input with nothing to read (no dataset ID, file address or valid creator) or nothing to judge by (no `brief` or `mustHave`), a run whose maximum charge is below the start fee (it stops before reading), profiles that failed on our side (also a refusal right after one of our failed attempts), invalid entries, the same creator twice, AI answers we threw away, notices and the report row.
- Two runs of the same input at the same time each score and charge on their own.

### Good to know

- **How much a run reads:** at most 3 rows per creator of `maxCreators` (default 500 → 1,500 rows; at most 20,000 rows of datasets and files in all), 5 MB of files and 120 seconds of reading. Past one of these, reading stops with a `source-budget` notice (not charged) and the creators read so far are judged. A video-per-row dataset (TikTok, Reels) has many rows per creator: raise `maxCreators` to read more of it.

- No contact details are collected. Contact fields in your data are carried over as they were. For YouTube business e-mails, run our [YouTube Channel Email Finder](https://apify.com/ntriqpro/youtube-channel-email-finder) on the same list first, then feed its dataset here.

- Keyword matching does not understand meaning (a word can appear in a negative sentence) — the quoted sentence is there so you can see why. The AI verdict is the layer that reads meaning.

- Verdicts are an aid to your own review, not a statement of fact about a person.

### Responsibility

Unofficial, independent tool, not affiliated with, endorsed by or sponsored by YouTube, Google, Instagram, Meta or TikTok. It judges the creator data you bring in (and, for YouTube channels you type in, the public About page read without logging in); it collects no contact details and sends no messages. You are responsible for having the right to use the data you bring in and a lawful basis to process it (for example under GDPR, CCPA or PIPA), for complying with anti-spam law (for example CAN-SPAM) when you contact anyone, and with the terms of the platforms the data came from. You are the data controller for the output.

# Actor input Schema

## `datasetIds` (type: `array`):

IDs (or console addresses) of datasets from other runs on your account, read with your own token. Field names of common scrapers are recognised as they come: our YouTube Channel Email Finder and YouTube Channel Monitor, Apify's Instagram Profile Scraper (username, biography, followersCount, latestPosts), TikTok scrapers (authorMeta, text, hashtags), YouTube e-mail scrapers (channelUrl, title or channelName, description, subscriberCount, email). Up to 10 datasets. A run reads at most 3 rows per creator of `maxCreators` (at most 20,000 rows of datasets and files in all), 5 MB of files and 120 seconds of reading; past that, reading stops with a notice and the creators read are judged. Reading is covered by the run-start fee (no event per row or file read).

## `csvUrls` (type: `array`):

Public http(s) addresses of CSV or JSON files (a JSON array, an object with `items`, or JSON lines), up to 5 MB in all (a line cut at the limit is dropped), up to 10 files. Column names as in the datasets above; Apify's flattened export headers (authorMeta/name, latestPosts/0/caption) are read. Reading is covered by the run-start fee (no event per row or file read).

## `creators` (type: `array`):

Profile addresses (youtube.com/@name, instagram.com/name, tiktok.com/@name), @handles (on the platform of `defaultPlatform`), instagram:name, tiktok:name or YouTube channel IDs. For YouTube channels typed here the public About page is read once (no login); a lookup YouTube refuses (HTTP 403 or 429) comes back as a row with accessRefused: true and is charged once as source-access-checked ($0.004 BRONZE) instead of a creator check. For Instagram and TikTok entries typed here only the handle is known, so the verdict is usually 'unclear' — bring a dataset with their bio and posts instead.

## `defaultPlatform` (type: `string`):

Which platform a bare @handle in `creators` belongs to.

## `brief` (type: `string`):

One or two sentences about the campaign and the creators you want (20-2,000 characters). Its topic words are matched against each creator's public text by the rules (all plans), and it is what the AI fit review judges against (paid plans).

## `mustHave` (type: `array`):

Words or phrases a good fit should mention (up to 30). All found → strong, some → possible, none → weak. Each match comes with the sentence it was found in.

## `exclude` (type: `array`):

Words or phrases that rule a creator out (up to 30), for example competitors or topics you avoid. A creator whose text holds one is marked excluded with the sentence; the AI review (paid) also flags exclusions said in other words.

## `minFollowers` (type: `integer`):

Creators below it are marked excluded (followerRange: below). Unknown follower counts are said, not excluded.

## `maxFollowers` (type: `integer`):

Creators above it are marked excluded (followerRange: above).

## `aiFit` (type: `boolean`):

Paid plans: an AI verdict (strong / possible / weak / unclear) per creator against your brief, with quotes from the creator's own text, the audience it states, topics and risk flags. $0.024 per verdict (BRONZE), charged only for verdicts that passed our checks (every quote is in the creator's text, no invented numbers). Creators without public text and creators your rules exclude are not sent. The creators' public text and your brief go to Anthropic's API (United States); no contact field is sent. On the free plan this is locked.

## `aiMaxItems` (type: `integer`):

The AI review stops after this many creators (paid plans).

## `shortlist` (type: `boolean`):

Paid plans: one row per run that ranks the creators (the AI verdict where there is one, else the rules) and counts why the others were excluded. $0.08 per run (BRONZE), made from 3 creators or more.

## `shortlistSize` (type: `integer`):

How many creators the shortlist lists.

## `maxCreators` (type: `integer`):

Paid plans: up to 5,000 creators per run. Free plan: the first 1 creator is judged in full by the rules; the rest (up to this number) come back as counts only in the free-plan-preview row (how many the rules rate strong or possible, weak, excluded or unclear, without saying who), with a fixed example of a paid row.

## `readYoutubeAbout` (type: `boolean`):

For YouTube channels in `creators` only: read the public About page once (description, subscribers, links) so there is text to judge. Creators from datasets and files are not read again.

## `proxyConfiguration` (type: `object`):

Off unless you turn it on. Used for the About pages of YouTube channels typed in.

## Actor input object example

```json
{
  "datasetIds": [
    "AbCdEf1234567890x"
  ],
  "csvUrls": [
    "https://example.com/creators.csv"
  ],
  "creators": [
    "@REI",
    "instagram:natgeo"
  ],
  "defaultPlatform": "youtube",
  "brief": "Outdoor gear brand looking for camping and hiking creators who review tents, backpacks and stoves for beginners.",
  "mustHave": [
    "camping",
    "tent"
  ],
  "exclude": [
    "casino",
    "vape"
  ],
  "aiFit": true,
  "aiMaxItems": 200,
  "shortlist": true,
  "shortlistSize": 10,
  "maxCreators": 500,
  "readYoutubeAbout": true
}
```

# Actor output Schema

## `dataset` (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 = {
    "creators": [
        "@REI",
        "@MyLifeOutdoors",
        "@mkbhd"
    ],
    "brief": "Outdoor gear brand looking for camping and hiking creators who review tents, backpacks and stoves for beginners."
};

// Run the Actor and wait for it to finish
const run = await client.actor("ntriqpro/influencer-fit-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 = {
    "creators": [
        "@REI",
        "@MyLifeOutdoors",
        "@mkbhd",
    ],
    "brief": "Outdoor gear brand looking for camping and hiking creators who review tents, backpacks and stoves for beginners.",
}

# Run the Actor and wait for it to finish
run = client.actor("ntriqpro/influencer-fit-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 '{
  "creators": [
    "@REI",
    "@MyLifeOutdoors",
    "@mkbhd"
  ],
  "brief": "Outdoor gear brand looking for camping and hiking creators who review tents, backpacks and stoves for beginners."
}' |
apify call ntriqpro/influencer-fit-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ntriqpro/influencer-fit-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/7zzNftuXviaLuPj4L/builds/z8Fzq8cTJHyrtiRY5/openapi.json