Tracking a TikTok hashtag campaign requires daily data on view counts, video submissions, individual post metrics, and comment sentiment. The API approach uses three Scavio TikTok endpoints: the hashtag endpoint for aggregate stats and the hashtag id, hashtag videos for individual posts, and video comments for sentiment. A daily Python pipeline captures all of this at 1 credit per request, giving you real campaign performance data instead of guessing from the app.
Campaign tracking requirements
When you run a branded hashtag campaign (e.g., #TryBrandX), you need to answer: How many total views has the hashtag received? How many videos have been created? Which individual videos are performing best? What is the sentiment in comments? Is participation growing or declining? Manual checking through the TikTok app gives you a snapshot. API tracking gives you a time series.
The three endpoints
import requests, os, json
from datetime import datetime
BASE = "https://api.scavio.dev/api/v1/tiktok"
AUTH = {"Authorization": f"Bearer {os.environ['SCAVIO_API_KEY']}"}
def get_hashtag_overview(hashtag: str) -> dict:
"""Get aggregate hashtag stats and the hashtag id. 1 credit."""
resp = requests.post(f"{BASE}/hashtag",
headers=AUTH,
json={"hashtag_name": hashtag},
timeout=30)
info = resp.json()["data"]["challengeInfo"]
stats = info.get("statsV2", {})
return {
"hashtag": hashtag,
"hashtag_id": info["challenge"]["id"],
"view_count": int(stats.get("viewCount", 0)),
"video_count": int(stats.get("videoCount", 0)),
"checked_at": datetime.now().isoformat()
}
def get_hashtag_top_videos(hashtag_id: str, count: int = 20) -> list[dict]:
"""Get individual videos using the hashtag. 1 credit."""
resp = requests.post(f"{BASE}/hashtag/videos",
headers=AUTH,
json={"hashtag_id": hashtag_id, "count": count},
timeout=30)
videos = resp.json()["data"].get("aweme_list", [])
return [{
"id": v.get("aweme_id"),
"author": v.get("author", {}).get("unique_id"),
"views": v.get("statistics", {}).get("play_count", 0),
"likes": v.get("statistics", {}).get("digg_count", 0),
"comments": v.get("statistics", {}).get("comment_count", 0),
"shares": v.get("statistics", {}).get("share_count", 0),
"description": v.get("desc", "")[:200],
"created": v.get("create_time")
} for v in videos]
def get_video_sentiment(video_id: str) -> dict:
"""Get comments for sentiment analysis. 1 credit."""
resp = requests.post(f"{BASE}/video/comments",
headers=AUTH,
json={"video_id": video_id, "count": 50},
timeout=30)
comments = resp.json()["data"].get("comments") or []
positive_words = ["love", "amazing", "great", "best", "perfect", "need"]
negative_words = ["bad", "fake", "scam", "waste", "terrible", "hate"]
positive = sum(1 for c in comments
if any(w in c.get("text", "").lower() for w in positive_words))
negative = sum(1 for c in comments
if any(w in c.get("text", "").lower() for w in negative_words))
return {
"video_id": video_id,
"total_comments": len(comments),
"positive": positive,
"negative": negative,
"neutral": len(comments) - positive - negative
}Daily tracking pipeline
def daily_campaign_report(hashtag: str, history_file: str) -> dict:
"""Run daily. Appends to history for time-series analysis."""
# Load previous data
try:
with open(history_file, "r") as f:
history = json.load(f)
except FileNotFoundError:
history = []
# Get today's stats
overview = get_hashtag_overview(hashtag)
top_videos = get_hashtag_top_videos(overview["hashtag_id"], count=10)
# Check sentiment on top 3 videos (3 additional credits)
sentiments = []
for v in top_videos[:3]:
if v["id"]:
sentiments.append(get_video_sentiment(v["id"]))
# Calculate daily deltas
today = {
"date": datetime.now().strftime("%Y-%m-%d"),
"total_views": overview["view_count"],
"total_videos": overview["video_count"],
"top_video_views": top_videos[0]["views"] if top_videos else 0,
"avg_sentiment": sum(s["positive"] for s in sentiments) /
max(sum(s["total_comments"] for s in sentiments), 1),
"new_views_today": 0,
"new_videos_today": 0
}
if history:
yesterday = history[-1]
today["new_views_today"] = today["total_views"] - yesterday.get("total_views", 0)
today["new_videos_today"] = today["total_videos"] - yesterday.get("total_videos", 0)
history.append(today)
# Save updated history
with open(history_file, "w") as f:
json.dump(history, f, indent=2)
return today
# Daily cost: 1 (overview) + 1 (videos) + 3 (sentiments) = 5 credits = $0.025/dayAlerting on campaign milestones
def check_campaign_alerts(today: dict, thresholds: dict) -> list[str]:
"""Generate alerts when campaign hits milestones or anomalies."""
alerts = []
if today["new_views_today"] > thresholds.get("viral_day_views", 500000):
alerts.append(f"Viral day: {today['new_views_today']:,} new views")
if today["new_videos_today"] > thresholds.get("high_participation", 50):
alerts.append(f"High participation: {today['new_videos_today']} new videos")
if today["new_views_today"] < thresholds.get("min_daily_views", 1000):
alerts.append(f"Low activity: only {today['new_views_today']:,} views today")
if today["avg_sentiment"] < thresholds.get("min_sentiment", 0.3):
alerts.append(f"Negative sentiment spike: {today['avg_sentiment']:.0%} positive")
return alertsReporting to stakeholders
Run the pipeline daily via cron. Accumulate 7-day and 30-day summaries. Key metrics for campaign reports: total views (growth curve), total UGC videos created (participation rate), top performing creator (potential collaboration), sentiment trend (brand safety), and views per video (content quality signal). All from 5 API calls per day at $0.025/day total cost.
Campaign cost vs monitoring cost
A typical branded hashtag campaign budget is $10,000-50,000 (influencer fees, paid promotion, creative production). Monitoring that campaign via API costs $0.75/month (5 credits/day for 30 days). Compare to TikTok analytics tools like Kalodata at $59-79/month or manual daily checking (30 minutes/day of someone scrolling the app). The API approach is cheaper and provides structured data you can trend over time.