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

### 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/hT7fiR71hbmbzvf2C/openapi.json