tiktok-research

TikTok Research

Research high-performing TikTok videos, identify outliers, and analyze top video content for hooks and structure.

Prerequisites

• APIFY_TOKEN environment variable or in .env
• GEMINI_API_KEY environment variable or in .env
• apify-client and google-genai Python packages
• Accounts configured in .claude/context/tiktok-accounts.md

Verify setup:

python3 -c "
import os
try:
    from dotenv import load_dotenv
    load_dotenv()
except ImportError:
    pass
from apify_client import ApifyClient
from google import genai
assert os.environ.get('APIFY_TOKEN'), 'APIFY_TOKEN not set'
assert os.environ.get('GEMINI_API_KEY'), 'GEMINI_API_KEY not set'
" && echo "Prerequisites OK"

Workflow

1. Create Run Folder

RUN_FOLDER="tiktok-research/$(date +%Y-%m-%d_%H%M%S)" && mkdir -p "$RUN_FOLDER" && echo "$RUN_FOLDER"

2. Fetch Content

python3 .claude/skills/tiktok-research/scripts/fetch_tiktok.py \
  --days 30 \
  --limit 50 \
  --sorting latest \
  --output {RUN_FOLDER}/raw.json

Parameters:

• --days: Days back to search (default: 30)
• --limit: Max videos per account (default: 50)
• --sorting: "latest", "popular", or "oldest" (default: latest)
• --usernames: Override accounts file with specific usernames

3. Identify Outliers

python3 .claude/skills/tiktok-research/scripts/analyze_posts.py \
  --input {RUN_FOLDER}/raw.json \
  --output {RUN_FOLDER}/outliers.json \
  --threshold 2.0

Output JSON contains:

• total_videos: Number of videos analyzed
• outlier_count: Number of outliers found
• topics: Top hashtags, sounds, and keywords
• accounts: List of accounts analyzed
• outliers: Array of outlier videos with engagement metrics

4. Analyze Top Videos with AI

python3 .claude/skills/video-content-analyzer/scripts/analyze_videos.py \
  --input {RUN_FOLDER}/outliers.json \
  --output {RUN_FOLDER}/video-analysis.json \
  --platform tiktok \
  --max-videos 5