Guide

Find viral TikTok creators with the API

A million views means something different for a 500-follower account than for a celebrity. "Viral" only means something relative to a creator's own baseline — so the useful question isn't "how many views," it's "is this an outlier for them." Here's how to check, in two calls.

Step 1: Look up the creator

GET /v1/satellite/creator/:platform/:username returns a creator's profile, stats, and recent videos. It's an async job — kick it off, then poll the status endpoint until it completes.

import requests, time

# Start creator lookup
response = requests.get(
    'https://api.virlo.ai/v1/satellite/creator/tiktok/hatimsshorts',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'include': 'videos,outliers', 'max_videos': 20}
)
job_id = response.json()['data']['job_id']

# Poll every 10 seconds until complete
while True:
    result = requests.get(
        f'https://api.virlo.ai/v1/satellite/creator/status/{job_id}',
        headers={'Authorization': 'Bearer YOUR_API_KEY'}
    ).json()['data']

    if result['status'] == 'completed':
        break
    time.sleep(10)

creator = result['result']
print(f"Followers: {creator['profile']['followers']}")
print(f"Avg views: {creator['stats']['avg_views']}")
print(f"Engagement rate: {creator['stats']['engagement_rate']}")

Step 2: Check their best video against their own baseline

Take the creator's top video by view count and run it through POST /v1/satellite/video-outlier. The response scores it against that creator's own catalogue, not a global threshold — so a nano-creator's mega_viral and a megastar's mega_viral are both genuine outliers relative to their own audience — which is the point.

# Get the top-performing video URL from the creator's videos
top_video = max(creator['videos'], key=lambda v: v['views'])

# Start video outlier analysis
response = requests.post(
    'https://api.virlo.ai/v1/satellite/video-outlier',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'url': top_video['url'], 'platform': 'tiktok'}
)
job_id = response.json()['data']['job_id']

# Poll until complete
while True:
    result = requests.get(
        f'https://api.virlo.ai/v1/satellite/video-outlier/status/{job_id}',
        headers={'Authorization': 'Bearer YOUR_API_KEY'}
    ).json()['data']

    if result['status'] == 'completed':
        break
    time.sleep(10)

analysis = result['result']['analysis']
print(f"Outlier score: {analysis['outlier_score']}")   # vs this creator's own baseline
print(f"Percentile: {analysis['percentile']}")          # 0-100 within their catalogue
print(f"Label: {analysis['performance_label']}")        # average | above_average | viral | mega_viral

Cost

$0.50 for the creator lookup, $0.50 for the video outlier analysis — $1.00 total, billed from your prepaid balance.

Full reference

For every parameter and response field, see the Satellite documentation. This same call sequence is also documented as the Creator Deep Dive recipe. To watch a niche or creator continuously instead of a single lookup, see Content Research Agents.

Get an API key