POST /v1/videos/track

Start tracking videos across TikTok, Instagram, or YouTube. Track up to 50 videos in a single request. Returns immediate video IDs and begins 30-day automatic tracking.

📋 Overview

Property	Value
Method	`POST`
Endpoint	`https://api.influtics.com/v1/videos/track`
Auth Required	✅ Yes
Credits Cost	💳 30 credits per video

🔐 Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

📝 Request

Request Body

Field	Type	Required	Description
`urls`	`string[]`	✅ Required	Array of video URLs to track (max 50 per request)

Example Request

curl -X POST https://api.influtics.com/v1/videos/track \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.tiktok.com/@username/video/1234567890",
      "https://www.instagram.com/reel/ABC123DEF456/",
      "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "https://vt.tiktok.com/ZSHpobCM8BbnH-fbjKy/"
    ]
  }'

🎯 Supported Platforms

TikTok

https://www.tiktok.com/@username/video/1234567890
https://vm.tiktok.com/shortlink
https://vt.tiktok.com/shortlink
https://m.tiktok.com/@username/video/1234567890

Instagram

https://www.instagram.com/reel/ABC123DEF456/
https://instagram.com/p/ABC123DEF456/
https://www.instagram.com/p/ABC123DEF456/

YouTube

https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://youtu.be/dQw4w9WgXcQ
https://youtube.com/shorts/dQw4w9WgXcQ
https://www.youtube.com/shorts/dQw4w9WgXcQ

✅ Response

Success Response (200 OK)

{
    "success": true,
    "data": {
        "results": [
            {
                "index": 0,
                "url": "https://www.tiktok.com/@username/video/1234567890",
                "platform": "tiktok",
                "video_id": "77168374-dd2c-496a-b1ae-3d4944f48ccb",
                "external_video_id": "7489443966908189959",
                "status": "tracked",
                "error": null
            },
            {
                "index": 1,
                "url": "https://www.instagram.com/reel/ABC123DEF456/",
                "platform": "instagram",
                "video_id": "fb14c33f-cb0a-4ddc-b7be-bb9a08e3d969",
                "external_video_id": "ABC123DEF456",
                "status": "already_tracked",
                "error": null
            },
            {
                "index": 2,
                "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                "platform": "youtube",
                "video_id": "2b683ee8-ba57-4218-8f7e-2268f58dc8ba",
                "external_video_id": "dQw4w9WgXcQ",
                "status": "tracked",
                "error": null
            }
        ]
    },
    "meta": {
        "summary": {
            "total": 3,
            "tracked": 2,
            "already_tracked": 1,
            "errors": 0
        },
        "processing_time_ms": 5421,
        "request_id": "6e10c2ba-dda6-4a3d-92f1-8a224c5a088c"
    }
}

Response Fields

Field	Type	Description
`success`	`boolean`	Whether the request was successful
`data.results[]`	`array`	Array of results for each video
`data.results[].index`	`number`	Index of the video in the original request array
`data.results[].url`	`string`	The processed video URL (unshortened if applicable)
`data.results[].platform`	`string`	Detected platform (tiktok, instagram, youtube)
`data.results[].video_id`	`string`	Internal Influtics video ID (UUID)
`data.results[].external_video_id`	`string`	Platform-specific video ID
`data.results[].status`	`string`	Status: "tracked", "already_tracked", or "error"
`data.results[].error`	`string`	Error message if status is "error", null otherwise
`meta.summary.total`	`number`	Total number of videos processed
`meta.summary.tracked`	`number`	Number of new videos successfully tracked
`meta.summary.already_tracked`	`number`	Number of videos already being tracked
`meta.summary.errors`	`number`	Number of videos that failed to process
`meta.processing_time_ms`	`number`	Time taken to process the request (ms)
`meta.request_id`	`string`	Unique request identifier

⚠️ Error Responses

Validation Error (400 Bad Request)

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Missing required field: urls",
        "field": "urls",
        "request_id": "6e10c2ba-dda6-4a3d-92f1-8a224c5a088c"
    }
}

Rate Limit Error (429 Too Many Requests)

{
    "success": false,
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Rate limit exceeded. Please try again later.",
        "request_id": "6e10c2ba-dda6-4a3d-92f1-8a224c5a088c"
    }
}

Subscription Limit Error (403 Forbidden)

{
    "success": false,
    "error": {
        "code": "SUBSCRIPTION_LIMIT",
        "message": "Video limit reached. Your Pro plan allows 1000 tracked videos. Current usage: 1000",
        "request_id": "6e10c2ba-dda6-4a3d-92f1-8a224c5a088c"
    }
}

🔧 Features

Automatic URL Processing

Platform Detection: Automatically detects platform from URL
URL Unshortening: Automatically unshortens TikTok shortened URLs (vt.tiktok.com, vm.tiktok.com)
Duplicate Prevention: Prevents tracking the same video multiple times
Error Handling: Continues processing other videos if one fails

Batch Processing Benefits

Efficiency: Process up to 50 videos in a single request
Cost Effective: Same credit cost per video as individual requests
Faster: Reduced API calls for bulk operations
Detailed Results: Individual status for each video in the batch

🎯 Use Cases

Influencer Campaigns: Track video performance for sponsored content
Competitor Analysis: Monitor competitor video metrics in bulk
Content Strategy: Analyze which content performs best across multiple videos
Brand Monitoring: Track mentions and branded content at scale
Performance Benchmarking: Compare video performance across platforms
Bulk Import: Import existing video lists for tracking

📈 What Happens Next?

First Stats: First stats tracked within 5 minutes
30-Day Tracking: Automatic daily updates for 30 days
Historical Data: Access to performance trends and growth
Dashboard Access: View all tracked videos in your dashboard

📊 Rate Limits

Multi-Video: 20 requests per minute (max 50 videos per request)
Total Videos: 1000 videos per minute across all requests

Related: Get Video Stats → | View Usage →