# TikTok Viral & Trend Radar — Video Growth ✅ (`nexascout/tiktok-viral-radar`) Actor

Discover TikTok videos by topic. Compare views with creator followers, track view growth between runs, and export ranked video research with engagement metrics. No TikTok login or API key required.

- **URL**: https://apify.com/nexascout/tiktok-viral-radar.md
- **Developed by:** [NexaScout](https://apify.com/nexascout) (community)
- **Categories:** Social media, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 video research results

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 Viral & Trend Radar

Find TikTok videos by topic, compare their public performance and track how their view counts change between runs. Use the results for content research, competitor monitoring and spotting videos that reach beyond a creator's follower count.

**No TikTok login or external API key required.** Results export to JSON, CSV and Excel and are available through the Apify API.

### What you get

- Video and creator links, captions, publication times and available public counters.
- Views relative to creator followers, engagement rates and a transparent research score.
- Measured view growth when a previously observed video appears again.
- Historical author comparisons based on videos captured in your research history.
- Three result views: **Video research**, **Growth between runs**, and **Public video metrics**.

### Quick start

1. Enter one or two topics.
2. Choose a publication-age cutoff and maximum results.
3. Run the Actor and open the Video research table.
4. To monitor growth, rerun the same settings after at least the minimum comparison interval.

```json
{
  "searchQueries": ["skincare routine", "makeup tutorial"],
  "region": "US",
  "maxAgeHours": 168,
  "minViews": 1000,
  "maxResults": 25,
  "saveHistory": true,
  "historyProfile": "beauty-radar"
}
```

Start with the included residential proxy setting. If you change the region, also set the proxy country to match. Region localizes search; it does not identify a video's audience country or a creator's residence.

A result limit is a maximum. Tight filters or a smaller available search sample can return fewer results, including zero.

### Understand the signals

| Field | Meaning |
| --- | --- |
| `views`, `likes`, `comments`, `shares` | Public counters returned for the observation. Missing values remain null. |
| `reachMultiple` | Views divided by the creator's available follower count. It is not unique audience reach. |
| `engagementRatePct` | 100 × (likes + comments + shares) / views. |
| `averageViewsPerHourSincePublished` | Lifetime average: views divided by the video's age. This is not its current growth rate. |
| `measuredViewsPerHour` | Change in reported views divided by elapsed hours between valid observations of the same video. |
| `viewsDelta` | Change in reported views between those observations. |
| `velocityVsBaseline` | Lifetime average view rate divided by the author's median rate from previously observed videos. Check `authorBaselineVideos` to see how much history supports it. |
| `viralScore` | A ranking heuristic based on available reach, likes and measured growth signals. It is not a prediction or probability. |
| `videoUrl`, `authorUrl` | Direct links when a creator handle is available. |
| `category`, `language` | Caption-based heuristics, not verified TikTok classifications. |

All discovered candidates are considered within the time budget. Matching candidates are ranked before the output limit is applied.

### Monitor growth over time

Keep **search queries, region, language, categories and historyProfile** consistent. Turn on `saveHistory`; use different history profiles for independent research.

The default minimum interval is **60 minutes**, with a **72-hour** comparison window. A first run establishes history. Later runs can measure growth only when the same video reappears. An author comparison becomes available once that author has usable prior history; a small observed sample is not the author's complete catalog.

- **BASELINE / NEW:** first observation in this research history.
- **INSUFFICIENT_INTERVAL:** the next observation is too soon for a valid rate.
- **RISING / STABLE:** measured growth is above/below your threshold.
- **ACCELERATING / DECLINING:** a comparison of consecutive valid growth intervals; this needs at least three suitable observations.
- **COUNTER_CORRECTION / STALE_BASELINE:** counters decreased or prior data is outside the comparison window.

A zero measured rate means the reported counter was unchanged. Public counters can be rounded or updated in batches, so short intervals can produce noisy rates. This Actor does not provide real-time streaming.

### Filters and search coverage

Use `minViews`, `minReachMultiple`, `maxAgeHours` or `maxAgeDays` to narrow results. If both age limits are nonzero, both apply. Set an age limit to 0 to disable it. Unknown publication dates are excluded when an age filter is active.

Language and category filters are heuristic. A language filter retains videos whose language could not be determined. A minimum reach filter retains videos with unknown follower data; inspect null reach values when a strict manual review matters.

Search is a bounded, changing sample, not all TikTok. Results can vary between runs. Search access can be temporarily unavailable. Broader discovery settings can increase run time; start with the default limits.

### Pricing

**$0.03 per run start + $0.005 per returned video** at the default 1 GB memory setting.

| Returned videos | Example run charge |
| --- | ---: |
| 0 | $0.03 |
| 25 | $0.155 |
| 50 | $0.28 |
| 100 | $0.53 |

The start event applies even when no videos match. It is charged once per allocated GB, with a minimum of one event. A video returned again on a later monitoring run is charged again. Only rows written to the default dataset generate result events; discovered candidates and filtered-out videos do not.

Set a maximum charge in Apify Console. The Actor respects the available result budget and can finish with a partial result when that budget is reached. Default memory is 1 GB and the Actor's configured maximum is 1 GB.

### Example research Tasks

- **Beauty & Skincare:** skincare routines and makeup tutorials.
- **AI Tools & Tech:** AI tools and useful gadgets.
- **Food & Recipes:** easy dinners and meal prep.
- **Fitness & Workouts:** home workouts and gym content.
- **Gaming Content:** Minecraft challenges and Fortnite gameplay.

Each example has its own history profile. Reuse that Task to build comparable observations.

### Support

Include your Apify run ID and a short description of the expected result when contacting the developer. The run summary explains empty or partial results.

# Changelog

This Actor's version history is a separate document: https://apify.com/nexascout/tiktok-viral-radar/changelog.md

# Actor input Schema

## `searchQueries` (type: `array`):

Topics or keywords to discover videos for. Use up to 10 queries; results are a bounded search sample.

## `region` (type: `string`):

Two-letter region for search localization + residential proxy country.

## `maxAgeHours` (type: `integer`):

Keep videos published within this many hours. 0 disables this cutoff. Unknown publication dates are excluded when an age cutoff is active.

## `maxAgeDays` (type: `integer`):

Only videos published within this many days (0 = no filter).

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

Minimum play count.

## `minReachMultiple` (type: `number`):

Minimum views / creator followers when follower data is available. Unknown reach is kept. 0 disables this filter.

## `maxResults` (type: `integer`):

Maximum returned videos after filtering and ranking; a matching result count is not guaranteed.

## `maxCandidatesPerQuery` (type: `integer`):

Videos to request per search page.

## `maxPagesPerQuery` (type: `integer`):

Search pages to fetch per keyword.

## `maxRunSeconds` (type: `integer`):

Soft collection time budget.

## `language` (type: `string`):

Detected caption language code, or any. This heuristic filter keeps videos with unknown language.

## `categories` (type: `array`):

Optional category allow-list (empty = all). Deterministic title heuristic.

## `saveHistory` (type: `boolean`):

Save observations for measured growth on later runs. Keep queries, region, language, categories and history profile consistent.

## `historyProfile` (type: `string`):

A short name to keep this research history separate, using letters, numbers and hyphens.

## `minIntervalMinutes` (type: `integer`):

Minimum gap between velocity samples.

## `maxComparisonHours` (type: `integer`):

Maximum lookback for a velocity sample.

## `risingViewsPerHour` (type: `integer`):

Velocity threshold to mark a video RISING.

## `accelerationFactor` (type: `number`):

Velocity ratio to mark ACCELERATING.

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

Residential proxy for the TikTok API requests.

## Actor input object example

```json
{
  "searchQueries": [
    "hiking"
  ],
  "region": "US",
  "maxAgeHours": 72,
  "maxAgeDays": 0,
  "minViews": 1000,
  "minReachMultiple": 0,
  "maxResults": 25,
  "maxCandidatesPerQuery": 30,
  "maxPagesPerQuery": 2,
  "maxRunSeconds": 180,
  "language": "any",
  "categories": [],
  "saveHistory": true,
  "historyProfile": "default",
  "minIntervalMinutes": 60,
  "maxComparisonHours": 72,
  "risingViewsPerHour": 100,
  "accelerationFactor": 1.5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

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

// Run the Actor and wait for it to finish
const run = await client.actor("nexascout/tiktok-viral-radar").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("nexascout/tiktok-viral-radar").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 nexascout/tiktok-viral-radar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexascout/tiktok-viral-radar"
        }
    }
}
```

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/EoYrf6vZuymJcC8BT/builds/fKbWwixmuDlIngVcE/openapi.json