Skip to main content

​
Welcome to ContentStats.io API

Track social media video performance across TikTok, YouTube, Instagram, and Twitter with our simple REST API.

​
Base URL

https://contentstats.io/api/v1

​
Authentication

All API requests require authentication using an API key in the X-API-Key header: 
curl https://contentstats.io/api/v1/videos \
  -H "X-API-Key: cs_live_YOUR_KEY"

Get Your API Key

Learn how to create and manage API keys

​
Endpoints Overview

EndpointMethodDescription
/videos/trackPOSTStart tracking a video
/videosGETList all tracked videos
/videos/{id}GETGet video details with snapshots
/videos/{id}/stopPOSTStop tracking early
/usageGETGet usage and billing stats

​
Quick Example

Track a TikTok video: 
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/123",
    "duration_days": 7
  }'
Response: 
{
  "id": "cm5abc123",
  "video_link": "https://www.tiktok.com/@user/video/123",
  "platform": "tiktok",
  "status": "monitoring",
  "estimated_cost": 2.52
}

​
Rate Limiting

PlanRate Limit
Free60 requests/minute
Pro300 requests/minute
EnterpriseCustom
Rate limit headers included in responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200

Rate Limits Details

Learn about rate limiting and best practices

​
Error Handling

All errors return appropriate HTTP status codes with JSON responses: 
{
  "error": "Insufficient balance",
  "balance": 0.50,
  "estimated_cost": 2.52
}
Common status codes:
CodeMeaning
200Success
400Bad Request
401Unauthorized (invalid API key)
402Payment Required (insufficient balance)
403Forbidden (access denied)
404Not Found
429Too Many Requests (rate limited)
500Internal Server Error

Error Reference

Complete error codes and handling guide

​
Supported Platforms

PlatformMetrics
TikTokViews, Likes, Comments, Shares, Saves
YouTubeViews, Likes, Comments
InstagramLikes, Comments, Saves
Twitter/XViews, Likes, Retweets, Replies

​
Data Types

​
Video Object

{
  id: string;
  job_id: string;
  video_link: string;
  platform: 'tiktok' | 'youtube' | 'instagram' | 'twitter';
  status: 'monitoring' | 'completed' | 'paused' | 'error' | 'cancelled';
  monitoring_started: string; // ISO 8601
  monitoring_duration_days: number;
  days_remaining: number;
  current_metadata: object;
  created_at: string;
  last_updated: string;
}

​
Snapshot Object

{
  id: string;
  snapshot_id: string;
  snapshot_time: string; // ISO 8601
  views: string; // BigInt as string
  likes: string;
  comments: string;
  shares?: string;
  saves?: string;
  provider: string;
}

​
Pagination

List endpoints support pagination: 
curl "https://contentstats.io/api/v1/videos?limit=50" \
  -H "X-API-Key: YOUR_KEY"
Query parameters:
  • limit: Number of results (1-100, default: 50)
  • platform: Filter by platform
  • status: Filter by status

​
Webhooks (Coming Soon)

Subscribe to events:
  • snapshot.created
  • tracking.completed
  • balance.low

​
Best Practices

  • Store in environment variables
  • Never commit to version control
  • Rotate keys every 90 days
  • Use server-side only
  • Snapshots update hourly
  • Don’t poll faster than every hour
  • Use webhooks when available
  • Check balance before tracking
  • Set up auto top-up
  • Monitor usage endpoint regularly
  • Implement retry logic with exponential backoff
  • Handle rate limits gracefully
  • Log errors for debugging

​
API Endpoints

Track Video

POST /videos/track

List Videos

GET /videos

Get Video

GET /videos/

Stop Video

POST /videos//stop

Get Usage

GET /usage

​
Need Help?

Quickstart Guide

Get started in 5 minutes

FAQ

Common questions answered

Support

Contact our team

API Status

Check API status