Endpoint
POST https://contentstats.io/api/v1/videos/track
Authentication
Request Body
Full URL of the video to track. Must be a public video.Supported formats:
- TikTok:
https://www.tiktok.com/@user/video/123
- YouTube:
https://www.youtube.com/watch?v=VIDEO_ID
- Instagram:
https://www.instagram.com/p/POST_ID/
- Twitter:
https://twitter.com/user/status/123
Number of days to track the video (1-30)Cost calculation:Duration (days) × 24 hours × $0.015 per snapshot
Response
Unique identifier for this tracked video
External job ID for tracking
The video URL being tracked
Detected platform: tiktok, youtube, instagram, or twitter
Current status: monitoring, completed, paused, error, cancelled
Total days video will be tracked
Days remaining in tracking period
Estimated total cost in USD
ISO 8601 timestamp when tracking started
Code Examples
curl -X POST https://contentstats.io/api/v1/videos/track \
-H "Content-Type: application/json" \
-H "X-API-Key: cs_live_YOUR_KEY" \
-d '{
"video_link": "https://www.tiktok.com/@user/video/7234567890",
"duration_days": 7
}'
Response Example
{
"id": "cm5abc123def",
"job_id": "job_xyz789",
"video_link": "https://www.tiktok.com/@user/video/7234567890",
"platform": "tiktok",
"status": "monitoring",
"monitoring_duration_days": 7,
"days_remaining": 7,
"estimated_cost": 2.52,
"created_at": "2024-01-29T10:00:00.000Z"
}
Error Responses
400 Bad Request
Invalid request parameters:
{
"error": "Invalid request",
"details": [
{
"field": "video_link",
"message": "Invalid URL format"
}
]
}
- Invalid video URL format
- Duration outside 1-30 days range
- Missing required fields
401 Unauthorized
{
"error": "API key required"
}
X-API-Key header.
402 Payment Required
{
"error": "Insufficient balance",
"balance": 0.50,
"estimated_cost": 2.52,
"required": 2.02
}
404 Not Found
{
"error": "Video not found or is private"
}
500 Internal Server Error
{
"error": "Failed to start monitoring - invalid response from tracking API"
}
What Happens Next
After starting tracking:
- First snapshot collected within 60 minutes
- Hourly snapshots continue for the specified duration
- Balance charged $0.015 per snapshot
- Email notification when tracking completes
URL formats:https://www.tiktok.com/@username/video/1234567890
https://vm.tiktok.com/abc123/
https://www.tiktok.com/t/abc123/
- Views
- Likes
- Comments
- Shares
- Saves
URL formats:https://www.youtube.com/watch?v=VIDEO_ID
https://youtu.be/VIDEO_ID
https://www.youtube.com/embed/VIDEO_ID
URL formats:https://www.instagram.com/p/POST_ID/
https://www.instagram.com/reel/REEL_ID/
Best Practices
Verify sufficient balance before tracking:const usage = await fetch('https://contentstats.io/api/v1/usage', {
headers: { 'X-API-Key': apiKey }
}).then(r => r.json());
const estimatedCost = duration_days * 24 * 0.015;
if (usage.balance_usd < estimatedCost) {
throw new Error('Insufficient balance');
}
Validate video URLs before sending:function isValidVideoUrl(url) {
const patterns = [
/^https:\/\/(www\.)?tiktok\.com\/@[\w.-]+\/video\/\d+/,
/^https:\/\/(www\.)?youtube\.com\/watch\?v=[\w-]+/,
/^https:\/\/(www\.)?instagram\.com\/(p|reel)\/[\w-]+/,
/^https:\/\/(twitter|x)\.com\/\w+\/status\/\d+/
];
return patterns.some(pattern => pattern.test(url));
}
Save the returned id to retrieve data later:const result = await trackVideo(url, 7);
// Store in database
await db.trackedVideos.create({
contentStatsId: result.id,
videoUrl: url,
platform: result.platform,
startedAt: result.created_at
});
Check if already tracking before creating new job:// List existing videos
const existing = await fetch(
'https://contentstats.io/api/v1/videos?platform=tiktok',
{ headers: { 'X-API-Key': apiKey } }
).then(r => r.json());
// Check if URL already tracked
const alreadyTracking = existing.videos.find(
v => v.video_link === newUrl && v.status === 'monitoring'
);
if (alreadyTracking) {
return alreadyTracking; // Reuse existing
}
Next Steps
