# TikTok Outlier Finder: Viral Videos, Reels & YouTube Breakouts (`nerolabs/viral-outlier-finder`) Actor

Finds TikTok, Instagram Reels and YouTube videos that beat their own creator's normal: outlier score (views vs the creator's median), pace, engagement, breakout level, hook and hashtags, from any scraper dataset, CSV or Sheet. No scraping or login. Charged per video scored. Agent-ready: MCP, x402.

- **URL**: https://apify.com/nerolabs/viral-outlier-finder.md
- **Developed by:** [Adam Pearce](https://apify.com/nerolabs) (community)
- **Categories:** Social media, Marketing, Automation
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 video scoreds

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?

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

## TikTok Outlier Finder: Viral Videos, Reels & YouTube Breakouts

**Which of a creator's videos blew up, and why?** Give this actor the rows your TikTok, Instagram Reels or YouTube scraper already returned (a dataset, CSV or Google Sheet) and it scores every video against **that creator's own normal**: views divided by the median views of their other videos. A 1M-view video means nothing on a 50M-view channel and everything on a 20K one. This finds the videos that really broke out, so you can copy the hook, the format and the hashtags.

No scraping, no login, no AI fees: it is maths on rows you already have, so it runs in seconds.

### Who uses it

- **Content creators and social media managers** looking for proven video ideas in their niche: scrape 10 competitors, see which of their videos did 5x or 10x their normal.
- **Agencies and brands** picking creators: who has real breakout hits, not just a big follower count.
- **UGC and ad teams** finding hooks that already work before filming.
- **AI agents and n8n or Make flows** that run a scraper, then need the winners only.

### What you get for each video

| Field | What it means |
|---|---|
| `outlierScore` | Views divided by the creator's median views (the video itself left out). 2 = twice their normal. |
| `level` | `viral` (10x+), `strong` (5x+), `outlier` (over your threshold, 2x by default), `rising` (under 3 days old but gaining views far faster than usual), `normal`, `under` |
| `creatorMedianViews` | That creator's normal, from the videos you gave |
| `paceScore`, `viewsPerDay` | Views per day against their usual pace, so new videos are judged fairly |
| `engagementRate`, `engagementVsCreator` | (likes + comments + shares) / views, and how that compares with their normal |
| `viewsToFollowers` | Views divided by followers: above 3 means it reached far past their audience |
| `hook` | The first line of the caption, the words people read or hear first |
| `reason` | One plain sentence: "1.9M views, 6.3x nasa's median of 303K across 19 videos; engagement 1.9x their normal." |
| `rankInCreator`, `rankOverall` | Best first, inside each creator and across all |

Plus your scraper's own columns (light ones), the video URL, date, likes, comments, shares, saves and hashtags.

The run summary (key-value store `OUTPUT`) adds the **top 10 outliers**, **hashtags that overperform** (how much more often a hashtag shows up in outliers than in all videos) and **each creator's normal**: median views, number of outliers and their best video.

### Example output

```json
{
  "rankOverall": 4,
  "creator": "nasa",
  "platform": "tiktok",
  "level": "strong",
  "outlierScore": 6.27,
  "views": 1900000,
  "creatorMedianViews": 303000,
  "paceScore": 3.12,
  "engagementRate": 9.4,
  "engagementVsCreator": 1.9,
  "hook": "Suited up. Next stop: the International Space Station.",
  "reason": "1.9M views, 6.3x nasa's median of 303K across 19 videos; engagement 1.9x their normal.",
  "videoUrl": "https://www.tiktok.com/@nasa/video/..."
}
```

### Input

- **Datasets**: pick one or more scraper runs. Works with clockworks/tiktok-scraper and look-alikes, apify/instagram-reel-scraper, apify/instagram-scraper (posts), apify/instagram-profile-scraper (latest posts), streamers/youtube-scraper and look-alikes. Several datasets are merged, and the same video seen twice is counted once.
- **File or Google Sheet URL**: your own sheet works too. It needs a creator (username) column and a views column; likes, comments, shares, date, url and caption make it better.
- **Video rows**: JSON rows, handy for AI agents.
- **Outlier threshold**: 2 by default (twice their normal).
- **Videos needed per creator**: 5 by default (3 minimum). Scrape 10 to 30 videos per creator for a solid normal.
- **Group videos by**: the profile that was scraped (default) or the account that posted it. Instagram profiles show collab reels owned by other accounts; by default they count with the profile you scraped.
- **Rows to keep**: all videos, scored only, outliers and rising, or outliers only.

**Run it after your scraper automatically:** on your scraper's page open Integrations, add this actor, and set Datasets to `{{resource.defaultDatasetId}}`.

### How the score is worked out

1. Videos are grouped by creator. Pinned videos (old hits kept on top of a profile) are left out of the creator's normal, but still scored.
2. The normal is the **median** views of the creator's videos (not the average, so one huge hit does not hide the others), with the video being scored left out.
3. Videos under 3 days old are also judged on views per day, so a fresh video that is taking off shows as `rising`.
4. Everything is fixed rules in code, with the reason written on every row. Nothing is guessed.

### Pricing

Pay per event, no subscription:

- **$0.002 per video scored** (only videos that come back with an outlier score; videos with no views, creators with too few videos and anything filtered out are free)
- **$0.01 per CSV or Excel file**, only if you ask for one

Examples: 10 competitors x 30 videos = 300 videos = **$0.60**. A weekly check on 50 creators x 20 videos = 1,000 videos = **$2 a week**. Choosing "Outliers only" means you pay only for the outliers written.

### Agents, MCP and x402

Agent-ready: pay per event through Apify's MCP server (`mcp.apify.com/?tools=nerolabs/viral-outlier-finder`) or with x402 (USDC on Base) through Apify's agent payments, no account needed. Pass scraper rows in `data` or a dataset ID in `datasetIds`.

### FAQ

**Does it scrape TikTok or Instagram?** No. It only reads rows you give it, so it never breaks when a site changes and never needs a login. Use any scraper you like first.

**Why do some creators say "too few videos"?** A normal needs several videos. With 1 or 2 videos there is nothing to compare against, so those rows are written with the reason and not charged. Scrape more videos per creator.

**Is a high score proof the video is "good"?** It is proof it got far more views than that creator usually gets. The engagement comparison tells you whether people also liked it, or whether it was just pushed wide.

**Can I track the same creators every week?** Yes: schedule your scraper, add this actor as an integration, and append results to a named dataset to build a running list of winners.

If this found you a video idea worth copying, a review on the Apify Store helps a lot.

# Actor input Schema

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

One or more scraper datasets: TikTok scrapers (clockworks/tiktok-scraper and look-alikes), Instagram Reel, post or profile scrapers, YouTube scrapers. Scrape 10 to 30 videos per creator so their normal can be worked out. Every video column is kept. In an integration set it to \["{{resource.defaultDatasetId}}"].

## `fileUrl` (type: `string`):

A public link to a CSV, Excel, JSON or JSON Lines file: scraper rows, or your own sheet with a creator (username) and views column, plus likes, comments, shares, date, url and caption if you have them. A normal Google Sheets link works when shared as 'Anyone with the link can view'.

## `fileFormat` (type: `string`):

Leave on 'Detect automatically' unless the link has no file extension.

## `sheetName` (type: `string`):

Which sheet to read from an Excel workbook. Defaults to the first sheet.

## `data` (type: `array`):

Rows as JSON objects, for a quick run or an AI agent call, e.g. \[{"creator": "...", "platform": "tiktok", "views": 120000, "likes": 9000, "date": "2026-10-20", "url": "...", "caption": "..."}] or raw scraper rows.

## `minOutlierScore` (type: `number`):

A video counts as an outlier when its views are at least this many times the creator's median views. 2 = twice their normal. 5 and 10 mark strong and viral.

## `minVideosPerCreator` (type: `integer`):

A creator's normal is only worked out when at least this many of their videos have views (minimum 3). Creators with fewer are written with the reason and not charged.

## `lookbackDays` (type: `integer`):

Score and compare only videos posted in this many days. 0 = every video given.

## `excludePinned` (type: `boolean`):

Pinned videos are usually old hits kept on top of the profile; leaving them out of the median keeps each creator's normal honest. They are still scored.

## `groupBy` (type: `string`):

'The profile that was scraped' puts collab reels and videos that appear on a profile with that profile (what you asked the scraper for). 'The account that posted it' groups by the real owner instead.

## `minViews` (type: `integer`):

Leave out videos below this view count (not charged). 0 = no minimum.

## `keep` (type: `string`):

Which videos to write (only written videos with a score are charged). 'All' also writes videos that could not be scored with the reason.

## `keepOriginalFields` (type: `boolean`):

Keep your scraper's own columns (light ones, not media or nested lists) next to the new ones.

## `exportFormats` (type: `array`):

Also save the results as CSV or Excel in the run's key-value store (charged once per file).

## `outputDatasetName` (type: `string`):

Name of a dataset to append the results to, to keep a running list of outlier videos across runs.

## `maxItems` (type: `integer`):

Stop reading after this many input rows.

## Actor input object example

```json
{
  "fileUrl": "https://nerolabs-samples.nerolabs.workers.dev/sample-outlier-videos.json",
  "fileFormat": "auto",
  "minOutlierScore": 2,
  "minVideosPerCreator": 5,
  "lookbackDays": 0,
  "excludePinned": true,
  "groupBy": "auto",
  "minViews": 0,
  "keep": "all",
  "keepOriginalFields": true,
  "maxItems": 200000
}
```

# Actor output Schema

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

One row per video with outlier score, creator median, pace, engagement, level, hook and reason, best first.

## `summary` (type: `string`):

Outlier counts, top outliers, hashtags that overperform, each creator's normal, settings, export links and warnings.

# 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 = {
    "fileUrl": "https://nerolabs-samples.nerolabs.workers.dev/sample-outlier-videos.json"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nerolabs/viral-outlier-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 = { "fileUrl": "https://nerolabs-samples.nerolabs.workers.dev/sample-outlier-videos.json" }

# Run the Actor and wait for it to finish
run = client.actor("nerolabs/viral-outlier-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 '{
  "fileUrl": "https://nerolabs-samples.nerolabs.workers.dev/sample-outlier-videos.json"
}' |
apify call nerolabs/viral-outlier-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nerolabs/viral-outlier-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/dZoq98iSv0g5qu8QQ/builds/kGPldbwRMXBIhVtuo/openapi.json