# Multi-Platform Viral Content Tracker (`bovi/multi-platform-viral-tracker`) Actor

Track what's going viral on a topic across YouTube and Reddit in ONE run and ONE normalized schema. Ranked by viral velocity (engagement gained per hour). Stop stitching a separate scraper per platform. Pay per item.

- **URL**: https://apify.com/bovi/multi-platform-viral-tracker.md
- **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community)
- **Categories:** Social media, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.62 / 1,000 content-results

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/platform/actors/running/actors-in-store#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

### Multi-Platform Viral Content Tracker

Track what's going viral on a topic across **YouTube, Reddit, TikTok and Instagram** in one run, returned as one normalized, ranked feed — instead of stitching together four separate scrapers with four different field shapes. Each item carries a `velocity_score` (engagement gained per hour since it was posted), so you see what is gaining traction *right now*, not just what has the highest raw count.

#### What it does

- **YouTube** — free-text topic search (e.g. `"ai agents"`). Returns real view counts; exact publish time is not exposed by YouTube search, so `posted_at`/`age_hours` are derived from the relative "N weeks ago" label.
- **Reddit** — per-subreddit (Reddit's own free-text search blocks bots, so this actor tracks named subreddits instead). Pulls a wide recent-post pool per subreddit and velocity-ranks it; because the underlying API sorts by time, not score, this surfaces "what's being posted and gaining traction now" in the subreddits you name, not a guaranteed all-time-top list.
- **TikTok** — hashtag topic-discovery and/or known handles. Exact post timestamps, so velocity is fully accurate here.
- **Instagram** — known handles only (Instagram has no public hashtag search without a login). Reads the account's recent posts/reels with exact timestamps.

Each platform runs and degrades independently — if one platform errors or a handle is unreachable, the others still return their results.

#### Input

Ten input fields, grouped by what feeds which platform:

**Topic / account sources (leave any group empty to skip that platform):**

- `keywords` — topics to search on YouTube, e.g. `["ai agents", "home espresso"]`.
- `subreddits` — subreddit names for Reddit, without `r/`, e.g. `["artificial", "singularity"]`.
- `hashtags` — TikTok hashtags for topic discovery, without `#`.
- `tiktokHandles` — TikTok accounts to track, without `@`.
- `instagramHandles` — Instagram accounts to track, without `@`.

**Run controls:**

- `platforms` — which of `youtube` / `reddit` / `tiktok` / `instagram` to run (default: all four).
- `maxPerPlatform` — items pulled per platform per topic before ranking (default 25).
- `maxItems` — cap on total items returned across all platforms/topics; `0` = no cap (default 0).
- `sortBy` — `velocity_score` (default), `engagement`, `views`, `likes`, `comments`, or `posted_at`.
- `proxyConfiguration` — Apify Proxy, RESIDENTIAL group prefilled. Used for YouTube, TikTok and Instagram (TikTok/Instagram reject datacenter IPs); Reddit's API needs no proxy.

#### Output fields

Every row, regardless of platform, is normalized to the same shape: `rank`, `platform`, `content_id`, `url`, `title`, `author`, `author_url`, `description`, `posted_at`, `age_hours`, `views`, `likes` (Reddit: upvote score), `comments`, `engagement` (sum of available interaction signals), `velocity_score` (engagement ÷ age in hours, age floored at 2h), `thumbnail`, `query` (the topic/handle/hashtag the item was found under), `scraped_at`, and `platform_extra` — a dict of platform-specific extras (e.g. `subreddit`/`upvote_ratio` for Reddit, `duration_seconds`/`tags` for YouTube, `hashtags`/`share_count` for TikTok, `media_type`/`location_name` for Instagram).

Ranking is computed **within each platform**, then results are concatenated — a YouTube view count dwarfs a Reddit score, so a single cross-platform sort would always bury Reddit. Re-sort the combined output yourself if you need a single global order.

#### Pricing

Pay-per-result — see the Store pricing tab for the current rate. Each ranked item returned is one charged unit.

#### Notes

- Reddit and YouTube quality is bounded by what each platform's public/no-auth path exposes: Reddit surfaces recent-and-rising posts in the subreddits you name (not an all-time-top list), and YouTube's `likes` is always `None` (YouTube search doesn't expose it), so YouTube `engagement` is effectively its view count.
- TikTok and Instagram carry exact timestamps, so their `velocity_score` is the most precise of the four platforms.
- This actor supplies nothing on your behalf beyond the Apify Proxy connection already built in — no external keys or accounts required to run it.

# Actor input Schema

## `keywords` (type: `array`):

Topics to track, e.g. \["ai agents", "home espresso"]. Each is searched on every selected platform.

## `subreddits` (type: `array`):

Subreddits to track for viral posts this week (without r/), e.g. \["artificial", "singularity"]. Reddit is tracked per-subreddit because reddit.com blocks free-text bot search. Leave empty to skip Reddit.

## `hashtags` (type: `array`):

TikTok hashtags for topic discovery — what is going viral on a THEME right now (without #), e.g. \["homeespresso", "aiagents"]. Fetched via a resilient browser tier. Leave empty to skip TikTok hashtag discovery.

## `tiktokHandles` (type: `array`):

TikTok accounts to track (without @), e.g. \["tiktok"]. Returns their recent videos velocity-ranked. Leave empty to skip.

## `instagramHandles` (type: `array`):

Instagram accounts to track (without @), e.g. \["instagram"]. Returns their recent posts/reels velocity-ranked. Instagram has no public hashtag search without login, so it is handle-only. Leave empty to skip.

## `platforms` (type: `array`):

Which platforms to track. Default: all supported. Each is fed by its own input (YouTube←keywords, Reddit←subreddits, TikTok←hashtags/tiktokHandles, Instagram←instagramHandles) and skips gracefully if its input is empty.

## `maxPerPlatform` (type: `integer`):

How many items to pull from each platform for each topic before ranking.

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

Cap the ranked output across all platforms/topics. 0 = no cap (you are charged per returned item).

## `sortBy` (type: `string`):

velocity\_score = engagement per hour since posting (viral velocity); engagement = total interactions; or sort by views/likes/comments/recency.

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

Used for YouTube, TikTok and Instagram (TikTok/Instagram reject datacenter IPs; Reddit's open API needs no proxy). Leave default RESIDENTIAL for reliable access.

## Actor input object example

```json
{
  "keywords": [
    "ai agents"
  ],
  "subreddits": [],
  "hashtags": [],
  "tiktokHandles": [],
  "instagramHandles": [],
  "platforms": [
    "youtube",
    "reddit",
    "tiktok",
    "instagram"
  ],
  "maxPerPlatform": 25,
  "maxItems": 0,
  "sortBy": "velocity_score",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

Dataset of ranked items (rank, platform, title, author, url, posted\_at, views, likes, comments, engagement, velocity\_score, query, platform\_extra).

# 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 = {
    "keywords": [
        "ai agents"
    ],
    "subreddits": [],
    "hashtags": [],
    "tiktokHandles": [],
    "instagramHandles": [],
    "platforms": [
        "youtube",
        "reddit",
        "tiktok",
        "instagram"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("bovi/multi-platform-viral-tracker").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 = {
    "keywords": ["ai agents"],
    "subreddits": [],
    "hashtags": [],
    "tiktokHandles": [],
    "instagramHandles": [],
    "platforms": [
        "youtube",
        "reddit",
        "tiktok",
        "instagram",
    ],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("bovi/multi-platform-viral-tracker").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 '{
  "keywords": [
    "ai agents"
  ],
  "subreddits": [],
  "hashtags": [],
  "tiktokHandles": [],
  "instagramHandles": [],
  "platforms": [
    "youtube",
    "reddit",
    "tiktok",
    "instagram"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call bovi/multi-platform-viral-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bovi/multi-platform-viral-tracker"
        }
    }
}

```

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/dRDZeycKefIMXZU5k/builds/BgspjeHrMtth260Cd/openapi.json