Skip to main content
GET
/
api
/
v1
/
videos
List Videos
curl --request GET \
  --url https://api.example.com/api/v1/videos \
  --header 'X-API-Key: <x-api-key>'
{
  "videos": [
    {
      "id": "<string>",
      "job_id": "<string>",
      "video_link": "<string>",
      "platform": "<string>",
      "status": "<string>",
      "monitoring_started": "<string>",
      "monitoring_duration_days": 123,
      "days_remaining": 123,
      "current_metadata": {},
      "created_at": "<string>"
    }
  ],
  "total": 123,
  "limit": 123
}

Documentation Index

Fetch the complete documentation index at: https://contentstats.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

GET https://www.contentstats.io/api/v1/videos
Retrieve all videos you’re tracking, with optional filters for platform and status.

​
Authentication

​
X-API-Key
string
required
Your API key from the dashboard

​
Query Parameters

​
platform
string
Filter by platformOptions: tiktok, youtube, instagram, twitterExample: ?platform=tiktok
​
status
string
Filter by tracking statusOptions: monitoring, completed, paused, error, cancelledExample: ?status=monitoring
​
limit
integer
Number of results to return (1-100)Default: 50Example: ?limit=100

​
Response

​
videos
array
Array of video objects
​
total
integer
Number of videos in response
​
limit
integer
Applied limit

​
Code Examples

curl "https://www.contentstats.io/api/v1/videos" \
  -H "X-API-Key: cs_live_YOUR_KEY"

​
Response Example

{
  "videos": [
    {
      "id": "cm5abc123",
      "job_id": "job_xyz789",
      "video_link": "https://www.tiktok.com/@user/video/123",
      "platform": "tiktok",
      "status": "monitoring",
      "monitoring_started": "2024-01-29T10:00:00.000Z",
      "monitoring_duration_days": 7,
      "days_remaining": 5.5,
      "current_metadata": {
        "title": "Viral Dance Challenge",
        "creator": "@user"
      },
      "created_at": "2024-01-29T10:00:00.000Z"
    },
    {
      "id": "cm5def456",
      "job_id": "job_abc456",
      "video_link": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "platform": "youtube",
      "status": "completed",
      "monitoring_started": "2024-01-22T10:00:00.000Z",
      "monitoring_duration_days": 7,
      "days_remaining": 0,
      "current_metadata": {
        "title": "Never Gonna Give You Up"
      },
      "created_at": "2024-01-22T10:00:00.000Z"
    }
  ],
  "total": 2,
  "limit": 50
}

​
Use Cases

​
Dashboard - Active Videos

async function getActiveVideos() {
  const response = await fetch(
    'https://www.contentstats.io/api/v1/videos?status=monitoring',
    { headers: { 'X-API-Key': apiKey } }
  );
  
  const data = await response.json();
  
  return data.videos.map(v => ({
    id: v.id,
    platform: v.platform,
    url: v.video_link,
    daysLeft: v.days_remaining
  }));
}

​
Platform-Specific Analytics

async function getPlatformStats(platform) {
  const response = await fetch(
    `https://www.contentstats.io/api/v1/videos?platform=${platform}`,
    { headers: { 'X-API-Key': apiKey } }
  );
  
  const data = await response.json();
  
  const stats = {
    total: data.total,
    active: data.videos.filter(v => v.status === 'monitoring').length,
    totalDaysTracking: data.videos.reduce((sum, v) => sum + v.monitoring_duration_days, 0)
  };
  
  return stats;
}

const tiktokStats = await getPlatformStats('tiktok');
console.log('TikTok:', tiktokStats);

​
Combining Filters

# Get all completed TikTok videos
curl "https://www.contentstats.io/api/v1/videos?platform=tiktok&status=completed&limit=100" \
  -H "X-API-Key: YOUR_KEY"

# Get first 10 monitoring YouTube videos
curl "https://www.contentstats.io/api/v1/videos?platform=youtube&status=monitoring&limit=10" \
  -H "X-API-Key: YOUR_KEY"

​
Pagination

The API returns up to 100 videos per request. For more videos: 
async function getAllVideos() {
  const allVideos = [];
  let hasMore = true;
  let limit = 100;
  
  // Note: Current API doesn't support offset
  // This example shows the pattern for when pagination is added
  
  const response = await fetch(
    `https://www.contentstats.io/api/v1/videos?limit=${limit}`,
    { headers: { 'X-API-Key': apiKey } }
  );
  
  const data = await response.json();
  allVideos.push(...data.videos);
  
  return allVideos;
}
Coming soon: Cursor-based pagination for large result sets

​
Best Practices

Only request what you need:
// ❌ Don't: Get all videos when you only need TikTok
const all = await fetch('/api/v1/videos');
const tiktok = all.videos.filter(v => v.platform === 'tiktok');

// ✅ Do: Filter server-side
const tiktok = await fetch('/api/v1/videos?platform=tiktok');
Videos don’t change frequently:
const cache = new Map();
const TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedVideos(platform) {
  const key = `videos_${platform}`;
  const cached = cache.get(key);
  
  if (cached && Date.now() - cached.timestamp < TTL) {
    return cached.data;
  }
  
  const response = await fetch(
    `https://www.contentstats.io/api/v1/videos?platform=${platform}`,
    { headers: { 'X-API-Key': apiKey } }
  );
  
  const data = await response.json();
  cache.set(key, { data, timestamp: Date.now() });
  
  return data;
}
Monitor video status changes:
async function monitorStatusChanges() {
  const previous = new Map();
  
  setInterval(async () => {
    const response = await fetch('/api/v1/videos?status=monitoring');
    const data = await response.json();
    
    data.videos.forEach(video => {
      const prev = previous.get(video.id);
      
      if (prev && prev.days_remaining !== video.days_remaining) {
        console.log(`${video.id}: ${video.days_remaining} days left`);
      }
      
      previous.set(video.id, video);
    });
  }, 60 * 60 * 1000); // Check hourly
}

​
Error Responses

​
401 Unauthorized

{
  "error": "API key required"
}
Missing or invalid API key.

​
400 Bad Request

{
  "error": "Invalid platform",
  "valid_platforms": ["tiktok", "youtube", "instagram", "twitter"]
}
Invalid query parameter value.

​
Next Steps

Get Video Details

Retrieve individual video with snapshots

Track New Video

Start tracking a video

Stop Tracking

End monitoring early

Get Usage

Check balance and usage