Social Media Video Scraper API Documentation

Overview

The Social Media Video Scraper API allows you to extract video metadata and download links from various social media platforms. The API supports both GET and POST methods for flexibility in integration.

Base URL

https://vd.vidsaver.dev/

Supported Platforms

Facebook

Instagram

TikTok

Twitter/X

Threads

DailyMotion

Snapchat

Twitch

Authentication

This API supports optional API key authentication. When enabled, protected endpoints require a valid API key.

API Key Configuration

Authentication can be configured via environment variables:

API_KEY_ENABLED: Enable/disable API key authentication (default: false)
API_KEY: The API key value
API_KEY_HEADER: Custom header name for API key (default: X-API-Key)

Authentication Methods

When authentication is enabled, you can provide the API key using either:

1. Custom Header (Recommended)

X-API-Key: your-api-key-here

2. Authorization Bearer Token

Authorization: Bearer your-api-key-here

Check Authentication Status

Use the /api-key-status endpoint to check if authentication is required.

API Endpoints

GET /scrape

Extract video information using URL parameter.

Parameters

Parameter	Type	Required	Description
`url`	string	Required	The video URL to scrape
`user_state`	string	Optional	User state: "premium" or "free" (default: "free")

Example Request

GET /scrape?url=https%3A//www.facebook.com/AFV/videos/best-funny-videos/839920211572868/
Host: vd.vidsaver.dev
                

cURL Example

curl "https://vd.vidsaver.dev/scrape?url=https%3A//www.facebook.com/AFV/videos/best-funny-videos/839920211572868/"
                

POST /scrape

Extract video information using JSON body (Recommended for production).

Headers

Header	Value	Required
`Content-Type`	application/json	Required

Request Body

Field	Type	Required	Description
`url`	string (URL)	Required	The video URL to scrape
`user_state`	string	Optional	User state: "premium" or "free" (default: "free")

Example Request

POST /scrape
Host: vd.vidsaver.dev
Content-Type: application/json

{
  "url": "https://www.facebook.com/AFV/videos/best-funny-videos/839920211572868/",
  "user_state": "free"
}
                

cURL Example

curl -X POST "https://vd.vidsaver.dev/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.facebook.com/AFV/videos/best-funny-videos/839920211572868/", "user_state": "free"}'
                

GET /

Get API information and supported platforms.

Example Request

GET /
Host: vd.vidsaver.dev
                

Example Response

{
  "message": "Social Media Video Scraper API",
  "version": "1.0.0",
  "authentication": {
    "enabled": false,
    "required": false,
    "header": null
  },
  "endpoints": {
    "/": {
      "methods": ["GET"],
      "description": "API information and available endpoints",
      "authentication_required": false
    },
    "/scrape": {
      "methods": ["GET", "POST"],
      "description": "Extract video metadata from social media URLs",
      "authentication_required": false,
      "parameters": {
        "url": "Video URL to scrape",
        "user_state": "User state: premium or free (default: free)"
      }
    },
    "/api-key-status": {
      "methods": ["GET"],
      "description": "Get API key configuration status",
      "authentication_required": false
    },
    "/reload-config": {
      "methods": ["POST"],
      "description": "Reload configuration from .env file",
      "authentication_required": true
    },
    "/user-agent-stats": {
      "methods": ["GET"],
      "description": "Get user agent rotation statistics",
      "authentication_required": true
    },
    "/cookie-stats": {
      "methods": ["GET"],
      "description": "Get cookie usage and failure statistics",
      "authentication_required": true
    },
    "/cookie-stats/reset-dead": {
      "methods": ["POST"],
      "description": "Reset dead cookies for specific platforms",
      "authentication_required": true
    },
    "/cookie-stats/set-max-failures": {
      "methods": ["POST"],
      "description": "Update maximum failures threshold for cookies",
      "authentication_required": true
    },
    "/cookie-stats/dead-cookies": {
      "methods": ["GET"],
      "description": "Get dead cookies log organized by platform",
      "authentication_required": true
    },
    "/logs/stats": {
      "methods": ["GET"],
      "description": "Get today's request log statistics",
      "authentication_required": true
    },
    "/logs/today": {
      "methods": ["GET"],
      "description": "Get today's logs",
      "authentication_required": true
    },
    "/env-vars": {
      "methods": ["GET", "POST"],
      "description": "Get or update environment variables from .env file",
      "authentication_required": true
    }
  }
}
                

GET /api-key-status

Get API key configuration status.

Example Request

GET /api-key-status
Host: vd.vidsaver.dev
                

Example Response

{
  "api_key_enabled": false,
  "api_key_required": false,
  "api_key_header": "X-API-Key"
}
                

POST /reload-config

Reload configuration from .env file. Requires Authentication

Headers

Header	Value	Required
`X-API-Key`	your-api-key	Required

Example Request

POST /reload-config
Host: vd.vidsaver.dev
X-API-Key: your-api-key
                

Example Response

{
  "message": "Configuration reloaded successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}
                

GET /user-agent-stats

Get user agent rotation statistics. Requires Authentication

Headers

Header	Value	Required
`X-API-Key`	your-api-key	Required

Example Request

GET /user-agent-stats
Host: vd.vidsaver.dev
X-API-Key: your-api-key
                

GET /logs/stats

Get logging statistics. Requires Authentication

Headers

Header	Value	Required
`X-API-Key`	your-api-key	Required

Example Request

GET /logs/stats
Host: vd.vidsaver.dev
X-API-Key: your-api-key
                

GET /logs/today

Get today's logs. Requires Authentication

Headers

Header	Value	Required
`X-API-Key`	your-api-key	Required

Example Request

GET /logs/today
Host: vd.vidsaver.dev
X-API-Key: your-api-key
                

GET /cookie-stats

Get cookie usage and failure statistics. Requires Authentication

Headers

Header	Value	Required
`X-API-Key`	your-api-key	Required

Example Request

GET /cookie-stats
Host: vd.vidsaver.dev
X-API-Key: your-api-key
                

Example Response

{
  "success": true,
  "data": {
    "total_cookies": 25,
    "active_cookies": 20,
    "dead_cookies": 5,
    "platforms": {
      "instagram": {
        "total": 10,
        "active": 8,
        "dead": 2
      },
      "tiktok": {
        "total": 8,
        "active": 7,
        "dead": 1
      }
    }
  }
}
                

POST /cookie-stats/reset-dead

Reset dead cookies for specific platforms. Requires Authentication

Headers

Header	Value	Required
`X-API-Key`	your-api-key	Required

Query Parameters

Parameter	Type	Required	Description
`platform`	string	Optional	Specific platform to reset (e.g., instagram, tiktok). If not provided, resets all platforms
`user_state`	string	Optional	User state: premium or free (default: free)
`is_backup`	boolean	Optional	Whether to reset backup cookies (default: false)

Example Request

POST /cookie-stats/reset-dead?platform=instagram&user_state=free&is_backup=false
Host: vd.vidsaver.dev
X-API-Key: your-api-key
                

Example Response

{
  "success": true,
  "message": "Dead cookies reset for instagram platform (free, backup=false) and removed from log"
}
                

POST /cookie-stats/set-max-failures

Update the maximum number of failures before marking a cookie as dead. Requires Authentication

Headers

Header	Value	Required
`X-API-Key`	your-api-key	Required

Query Parameters

Parameter	Type	Required	Description
`max_failures`	integer	Required	Maximum number of sequential failures before marking cookie as dead

Example Request

POST /cookie-stats/set-max-failures?max_failures=5
Host: vd.vidsaver.dev
X-API-Key: your-api-key
                

Example Response

{
  "success": true,
  "message": "Maximum failures threshold updated to 5"
}
                

GET /cookie-stats/dead-cookies

Get the dead cookies log organized by platform. Requires Authentication

Headers

Header	Value	Required
`X-API-Key`	your-api-key	Required

Example Request

GET /cookie-stats/dead-cookies
Host: vd.vidsaver.dev
X-API-Key: your-api-key
                

Example Response

{
  "success": true,
  "data": {
    "instagram": [
      {
        "cookie_file": "instagram_cookies_1.txt",
        "failure_count": 5,
        "last_failure": "2024-01-15T10:30:00Z"
      }
    ],
    "tiktok": [
      {
        "cookie_file": "tiktok_cookies_2.txt",
        "failure_count": 3,
        "last_failure": "2024-01-15T09:15:00Z"
      }
    ]
  },
  "summary": {
    "total_platforms": 2,
    "total_dead_cookies": 2,
    "platforms": ["instagram", "tiktok"]
  }
}
                

GET /env-vars

Get all environment variables from .env file. Requires Authentication

Headers

Header	Value	Required
`X-API-Key`	your-api-key	Required

Example Request

GET /env-vars
Host: vd.vidsaver.dev
X-API-Key: your-api-key
                

Example Response

{
  "status": "success",
  "message": "Retrieved 25 environment variables",
  "data": {
    "API_KEY_ENABLED": "true",
    "API_KEY_HEADER": "X-API-Key",
    "FREE_FACEBOOK_PROXY": "http://proxy1.example.com:8080",
    "PREMIUM_INSTAGRAM_PROXY": "http://premium-proxy.example.com:8080"
  }
}
                

POST /env-vars

Set or update an environment variable in .env file with hot reload. Requires Authentication

Headers

Header	Value	Required
`Content-Type`	application/json	Required
`X-API-Key`	your-api-key	Required

Request Body

Field	Type	Required	Description
`key`	string	Required	Environment variable name
`value`	string	Required	Environment variable value

Example Request

POST /env-vars
Host: vd.vidsaver.dev
Content-Type: application/json
X-API-Key: your-api-key

{
  "key": "NEW_PROXY_URL",
  "value": "http://new-proxy.example.com:8080"
}
                

Example Response

{
  "status": "success",
  "message": "Environment variable 'NEW_PROXY_URL' updated successfully and configuration reloaded",
  "data": {
    "NEW_PROXY_URL": "http://new-proxy.example.com:8080"
  }
}
                

Response Format

Success Response

200 OK Successful Video Extraction

{
  "status": "success",
  "platform_name": "facebook",
  "data": {
    "metadata": {
      "video_title": "Best Funny Videos",
      "video_description": "This is the funniest thing I've seen all day! 🤣🤣",
      "video_hash_tag": "#funny #viral",
      "video_id": "839920211572868",
      "video_url": "https://www.facebook.com/AFV/videos/839920211572868/",
      "video_thumbnail_url": "https://thumbnail-url.jpg",
      "social_media_name": "facebook",
      "author_name": "America's Funniest Home Videos",
      "author_id": "AFV",
      "author_profile_url": "https://www.facebook.com/AFV",
      "author_profile_photo_url": "https://profile-photo-url.jpg",
      "duration_seconds": 120.5,
      "duration_formatted": "02:00"
    },
    "video_format": [
      {
        "format_id": "720p_mp4",
        "video_format_name": "720p MP4",
        "video_extension": "mp4",
        "protocol": "https",
        "video_size": "15.0 MB",
        "video_resolution": "1280x720",
        "video_download_url": "https://video-download-url.mp4",
        "has_audio": true,
        "duration_seconds": 120.5,
        "duration_formatted": "02:00"
      }
    ],
    "audio_format": [
      {
        "format_id": "audio_mp3",
        "audio_format_name": "MP3 Audio",
        "audio_size": "3.2 MB",
        "audio_extension": "mp3",
        "protocol": "https",
        "audio_quality": "128kbps",
        "audio_download_url": "https://audio-download-url.mp3",
        "duration_seconds": 120.5,
        "duration_formatted": "02:00"
      }
    ],
    "header": {
      "tt_chain_token": null
    }
  }
}
                

Error Response

400 Bad Request Extraction Failed

{
  "status": "fail",
  "platform_name": "facebook",
  "error": {
    "error_code": "EXTRACTION_FAILED",
    "error_message": "Video not available or private",
    "platform_name": "facebook",
    "url": "https://www.facebook.com/AFV/videos/839920211572868/",
    "ytdlp_error": "ERROR: Video unavailable",
    "additional_details": null
  }
}
                

Error Codes

Error Code	Description	HTTP Status
`INVALID_URL`	The provided URL is not valid or malformed	400
`UNSUPPORTED_PLATFORM`	The platform is not supported by the API	400
`EXTRACTION_FAILED`	Failed to extract video information (video may be private, deleted, or unavailable)	400
`TIMEOUT`	Request timeout while processing the video	408
`INTERNAL_ERROR`	Unexpected server error occurred	500

User States

The API supports two user states that affect proxy and cookie configuration:

Free Users (Default)

user_state: "free"
Description: Standard access with basic proxy and cookie configuration
Usage: Default state when no user_state is specified

Premium Users

user_state: "premium"
Description: Enhanced access with premium proxy and cookie configuration
Features: May have access to higher-quality proxies and specialized cookie configurations

Configuration

User state behavior is configured through environment variables:

Platform-specific proxy configurations for each user state
Cookie management settings per user state and platform
Backup proxy and cookie configurations for failover

# Example environment variables
PREMIUM_FACEBOOK_PROXY=http://premium-proxy:8080
FREE_FACEBOOK_PROXY=http://free-proxy:8080
PREMIUM_FACEBOOK_COOKIES=premium_facebook_cookies.txt
FREE_FACEBOOK_COOKIES=free_facebook_cookies.txt
            

Code Examples

JavaScript (Fetch API)

// GET Request
const url = 'https://vd.vidsaver.dev/scrape?url=' + encodeURIComponent(videoUrl) + '&user_state=free';
const headers = {};
// Add API key if authentication is enabled
if (apiKey) {
  headers['X-API-Key'] = apiKey;
}

fetch(url, { headers })
  .then(response => response.json())
  .then(data => {
    if (data.status === 'success') {
      console.log('Video Title:', data.data.metadata.video_title);
      console.log('Duration:', data.data.metadata.duration_formatted);
      console.log('Download URLs:', data.data.video_format);
    } else {
      console.error('Error:', data.error.error_message);
    }
  })
  .catch(error => console.error('Network Error:', error));

// POST Request
const requestHeaders = {
  'Content-Type': 'application/json'
};
// Add API key if authentication is enabled
if (apiKey) {
  requestHeaders['X-API-Key'] = apiKey;
}

fetch('https://vd.vidsaver.dev/scrape', {
  method: 'POST',
  headers: requestHeaders,
  body: JSON.stringify({
    url: videoUrl,
    user_state: 'free'
  })
})
.then(response => response.json())
.then(data => {
  // Handle response
});
            

Python (Requests)

import requests
import json

# Configuration
video_url = "https://www.facebook.com/AFV/videos/839920211572868/"
api_key = "your-api-key-here"  # Set to None if authentication is disabled

# GET Request
params = {"url": video_url, "user_state": "free"}
headers = {}
if api_key:
    headers["X-API-Key"] = api_key

response = requests.get("https://vd.vidsaver.dev/scrape", params=params, headers=headers)
data = response.json()

if data['status'] == 'success':
    print(f"Title: {data['data']['metadata']['video_title']}")
    print(f"Duration: {data['data']['metadata']['duration_formatted']}")
    for format in data['data']['video_format']:
        print(f"Quality: {format['video_resolution']} - URL: {format['video_download_url']}")
else:
    print(f"Error: {data['error']['error_message']}")

# POST Request
payload = {"url": video_url, "user_state": "free"}
headers = {"Content-Type": "application/json"}
if api_key:
    headers["X-API-Key"] = api_key

response = requests.post("https://vd.vidsaver.dev/scrape", 
                        data=json.dumps(payload), 
                        headers=headers)
data = response.json()
            

PHP (cURL)

 $videoUrl, "user_state" => "free"]);
$headers = ["Content-Type: application/json"];

// Add API key header if provided
if ($apiKey) {
    $headers[] = "X-API-Key: " . $apiKey;
}

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://vd.vidsaver.dev/scrape");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
            

Java (OkHttp)

import okhttp3.*;
import org.json.JSONObject;
import java.net.URLEncoder;

// Configuration
String videoUrl = "https://www.facebook.com/AFV/videos/839920211572868/";
String apiKey = "your-api-key-here"; // Set to null if authentication is disabled

// GET Request
String encodedUrl = URLEncoder.encode(videoUrl, "UTF-8");
String apiUrl = "https://vd.vidsaver.dev/scrape?url=" + encodedUrl + "&user_state=free";

OkHttpClient client = new OkHttpClient();
Request.Builder requestBuilder = new Request.Builder()
    .url(apiUrl)
    .get();

// Add API key header if provided
if (apiKey != null) {
    requestBuilder.addHeader("X-API-Key", apiKey);
}

Request request = requestBuilder.build();
Response response = client.newCall(request).execute();
String jsonResponse = response.body().string();

JSONObject data = new JSONObject(jsonResponse);

if (data.getString("status").equals("success")) {
    JSONObject metadata = data.getJSONObject("data").getJSONObject("metadata");
    System.out.println("Title: " + metadata.getString("video_title"));
    System.out.println("Duration: " + metadata.getString("duration_formatted"));
}

// POST Request
JSONObject payload = new JSONObject();
payload.put("url", videoUrl);
payload.put("user_state", "free");

RequestBody body = RequestBody.create(
    payload.toString(),
    MediaType.parse("application/json")
);

Request.Builder postRequestBuilder = new Request.Builder()
    .url("https://vd.vidsaver.dev/scrape")
    .post(body);

// Add API key header if provided
if (apiKey != null) {
    postRequestBuilder.addHeader("X-API-Key", apiKey);
}

Request postRequest = postRequestBuilder.build();
Response postResponse = client.newCall(postRequest).execute();
String postJsonResponse = postResponse.body().string();
JSONObject postData = new JSONObject(postJsonResponse);
            

Support

For issues or questions, please refer to the API error messages and status codes provided in the response. The API provides detailed error information to help you troubleshoot integration issues.

Common Issues

Video Not Available: The video may be private, deleted, or region-restricted
Platform Not Supported: Check the supported platforms list above
Invalid URL: Ensure the URL is properly formatted and accessible
Timeout Errors: Some videos may take longer to process; implement retry logic