API Documentation v2

Introduction

High-performance Social API with queue-based processing

API v2 Queue System

Our new API v2 uses an advanced queue system for optimal performance:

Task-based processing: Submit tasks and get results when ready
High performance: Supports 500+ RPS with ultra-high load capacity
Real-time status: Check task progress with detailed status updates
Reliable processing: Never lose data with persistent queue storage

Base URL

https://socket-app-jb.store/api

Authentication

To access the API, you need to include the API key in the X-API-Key header of each request. You can get a key after registration and account activation.

X-API-Key: your_api_key

Want to get started?

Create an account and get an API key to integrate with SocketStore.

API Endpoints

Click on any endpoint to view detailed documentation

YouTube Data Extraction

IG Downloads

YouTube Downloads

Task Management

Other

POST /api/v2/profile

1 request

Create a task to retrieve Instagram user profile information.

Returns a task ID that can be used to check status and retrieve results. This endpoint charges 1 request from your subscription plan.

user_link: Instagram profile URL (e.g., https://instagram.com/username)

task_id: Unique identifier for tracking the task
status: Always "pending" initially
message: Confirmation that task was queued

Request Body

{"example": "request"}

Example Response

{
  "task_id": "abc123-def456-ghi789",
  "status": "pending",
  "message": "Task created successfully"
}

POST /api/v2/reels

1 request

Create a task to retrieve Instagram user reels with pagination support.

Eliminating duplicate reels
Getting current view/like counts that match Instagram
More reliable data consistency

IMPORTANT: When requesting 12 reels, may return fewer if there are other posts (photos, carousels, etc.) between reels in the user's media feed.

Returns a task ID that can be used to check status and retrieve results. This endpoint charges 1 request from your subscription plan.

instagram_id: Instagram user ID (get from /profile endpoint)
count: Number of reels to fetch (maximum: 12, default: 12)
max_id: Pagination cursor from previous response (optional)
pagination: Enable pagination support (default: True)
True: Standard pagination mode (required for max_id compatibility)
False: Optimized cost mode - cheaper but no max_id support

IMPORTANT FOR PAGINATION: If you need to paginate through results (get next pages), set pagination=True. When pagination=False, cost-optimized mode won't provide valid max_id for next requests.

task_id: Unique identifier for tracking the task
status: Always "pending" initially
message: Confirmation that task was queued

Request Body

{"example": "request"}

Example Response

{
  "task_id": "abc123-def456-ghi789",
  "status": "pending",
  "message": "Task created successfully"
}

POST /api/v2/profile_and_reels

2 requests

Create a combined task to retrieve Instagram user profile information and reels.

This endpoint performs both profile and reels retrieval in a single task. Returns a task ID that can be used to check status and retrieve results. This endpoint charges 2 requests from your subscription plan.

user_link: Instagram profile URL (e.g., https://instagram.com/username)
count: Number of reels to fetch (maximum: 12, default: 12)
max_id: Pagination cursor from previous response (optional)
pagination: Enable pagination support for reels (default: True)
True: Standard pagination mode for reels (required for max_id compatibility)
False: Optimized cost mode for reels - cheaper but no max_id support

IMPORTANT FOR PAGINATION: If you need to paginate through reels results (get next pages), set pagination=True. When pagination=False, cost-optimized mode won't provide valid max_id for next requests.

task_id: Unique identifier for tracking the task
status: Always "pending" initially
message: Confirmation that task was queued

Request Body

{"example": "request"}

Example Response

{
  "task_id": "abc123-def456-ghi789",
  "status": "pending",
  "message": "Task created successfully"
}

POST /api/v2/youtube/channel

1 request

Create a task to retrieve YouTube channel information.

Returns a task ID that can be used to check status and retrieve results. This endpoint charges 1 request from your subscription plan.

channel_url: YouTube channel URL (e.g., https://youtube.com/@channelname)

task_id: Unique identifier for tracking the task
status: Always "pending" initially
message: Confirmation that task was queued

Request Body

{"channel_url": "https://www.youtube.com/@channelname"}

Example Response

{
  "task_id": "abc123-def456-ghi789",
  "status": "pending",
  "message": "Task created successfully"
}

POST /api/v2/youtube/videos

1 request

Create a task to retrieve YouTube channel videos.

Returns a task ID that can be used to check status and retrieve results. This endpoint charges 1 request from your subscription plan.

channel_id: YouTube channel ID

task_id: Unique identifier for tracking the task
status: Always "pending" initially
message: Confirmation that task was queued

Request Body

{"video_id": "dQw4w9WgXcQ"}

Example Response

{
  "task_id": "abc123-def456-ghi789",
  "status": "pending",
  "message": "Task created successfully"
}

POST /api/v2/youtube/shorts

1 request

Create a task to retrieve YouTube channel shorts.

Returns a task ID that can be used to check status and retrieve results. This endpoint charges 1 request from your subscription plan.

channel_id: YouTube channel ID

task_id: Unique identifier for tracking the task
status: Always "pending" initially
message: Confirmation that task was queued

Request Body

{"channel_id": "UCChannelID123"}

Example Response

{
  "task_id": "abc123-def456-ghi789",
  "status": "pending",
  "message": "Task created successfully"
}

POST /api/v2/youtube/video/info

1 request

Create a task to retrieve detailed YouTube video information.

Includes statistics: views, likes, comments, and other engagement metrics. Returns a task ID that can be used to check status and retrieve results. This endpoint charges 1 request from your subscription plan.

video_id: YouTube video ID

task_id: Unique identifier for tracking the task
status: Always "pending" initially
message: Confirmation that task was queued

Request Body

{"video_id": "dQw4w9WgXcQ"}

Example Response

{
  "username": "user@example.com",
  "subscription_tier": "pro",
  "requests_used": 150,
  "requests_limit": 1000,
  "is_active": true
}

POST /api/v2/youtube/shorts-info

1 request

Get detailed information about YouTube shorts

This endpoint retrieves comprehensive information about a specific YouTube short video including likes, comments, views, description, and other metadata.

Request cost: 1 API request

video_id: The YouTube shorts video ID

task_id: Unique identifier for tracking this task
status: Current task status (pending/processing/done/error)
message: Human-readable status message

Example usage: ```json { "video_id": "jOcyYhsc1mA" } ```

Request Body

{"channel_id": "UCChannelID123"}

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "pending", "message": "Task created successfully" }

POST /api/v2/youtube/dl
1 request

Create YouTube video file download task
This endpoint creates a background task to download YouTube videos as files. The download is processed asynchronously and the video file is available for 24 hours.
Cost: 1 API request
Regular videos: Any YouTube video URL
Shorts: YouTube Shorts videos
Various quality options available
`task_id`: Unique identifier for tracking the download
`status`: Current task status (pending, processing, completed, failed)
`message`: Status message
Use `/dl/{task_id}/status` to check progress (FREE)
When status is 'completed', use `/dl/{task_id}/file` to download

Request Body

{"channel_id": "UCChannelID123"}

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "pending", "message": "Task created successfully" }

GET /api/v2/youtube/dl/{task_id}/status
FREE

Get YouTube file download task status
Check the current status of a YouTube file download task. This endpoint is free to use and doesn't consume API requests.
Request cost: FREE
`pending`: Task is waiting to be processed
`processing`: File is being downloaded
`completed`: File is ready for download
`failed`: Download failed (check error_message)
`expired`: File download expired (24h limit)
task_id: The task identifier
status: Current task status
youtube_url: Original YouTube URL
created_at: Task creation timestamp
expires_at: When the download expires
file_ready: Whether file is ready for download
error_message: Error details if failed

URL Parameters

task_id: Parameter

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "completed", "created_at": "2024-01-01T00:00:00Z", "completed_at": "2024-01-01T00:00:30Z" }

GET /api/v2/youtube/dl/{task_id}/file
FREE

Download YouTube video file (one-time access)
Download the processed YouTube video file. This endpoint provides one-time access only. After downloading, the file is automatically deleted from the server.
Files are available for 24 hours after processing
Each file can only be downloaded once
File is automatically deleted after download
Task status must be 'completed' before download
Binary video file with appropriate Content-Type
Content-Disposition header for filename
Supports MP4, WebM, and other YouTube formats

URL Parameters

task_id: Parameter

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "completed", "result": { "data": "Task results here" } }

GET /api/v2/task/{task_id}
FREE

Retrieve the status and results of a previously created task.
This endpoint is FREE - no requests are charged.
Instagram profile tasks
Instagram reels tasks
YouTube channel tasks
YouTube videos tasks
YouTube shorts tasks
YouTube video info tasks
YouTube shorts info tasks
YouTube download tasks
task_id: The unique task identifier returned when creating the task
task_id: The task identifier
status: Current task status (pending, processing, completed, failed)
created_at: When the task was created
updated_at: When the task was last updated
result: Task results (only present when status is "completed")
error: Error message (only present when status is "failed")

URL Parameters

task_id: Parameter

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "completed", "result": { "data": "Task results here" } }

GET /api/v2/info
FREE

Get information about your API account, including usage statistics and limits.
This endpoint is FREE - no requests are charged.
username: Your account username
email: Your account email
subscription_tier: Your current subscription plan
requests_used: Number of API requests used this month
requests_limit: Total API requests allowed per month
subscription_expires: When your subscription expires
created_at: When your account was created

Example Response

{ "username": "user@example.com", "subscription_tier": "pro", "requests_used": 150, "requests_limit": 1000, "is_active": true }

GET /api/v2/queue/stats
FREE

Get queue statistics for monitoring purposes.
This endpoint is FREE - no requests are charged. Shows the number of tasks in different states in the queue.
total_tasks: Total number of tasks in queue
pending: Tasks waiting to be processed
processing: Tasks currently being processed
completed: Successfully completed tasks
failed: Tasks that failed during processing

Example Response

{ "success": true, "data": {} }

GET /api/v2/tasks/stats
FREE

Get database task statistics for monitoring purposes.
This endpoint is FREE - no requests are charged. Shows the number of tasks in different states in the database.
total_tasks: Total number of tasks in database
pending: Tasks waiting to be processed
processing: Tasks currently being processed
completed: Successfully completed tasks
failed: Tasks that failed during processing

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "completed", "result": { "data": "Task results here" } }

POST /api/ig/download
5 requests

Create Instagram video download task
This endpoint creates a background task to download Instagram videos. The download is processed asynchronously and the video is available for 24 hours.
Cost: 5 requests per download
Posts: `/p/[post_id]`
Reels: `/reel/[reel_id]` or `/reels/[reel_id]`
Stories: `/stories/[story_id]`
Share links: `/share/[share_id]`
`task_id`: Unique identifier for tracking the download
`status`: Current task status (pending, processing, completed, failed)
`instagram_url`: The original Instagram URL
`created_at`: Task creation timestamp
`message`: Status message
Use `/ig/download/{task_id}/status` to check progress
When status is 'completed', use `/ig/download/{task_id}/file` to download

Request Body

{"example": "request"}

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "pending", "message": "Task created successfully" }

GET /api/ig/download/{task_id}/status
FREE

Get Instagram download task status
`pending`: Task is queued for processing
`processing`: Video is being downloaded
`completed`: Video is ready for download
`failed`: Download failed (check error_message)
`task_id`: Task identifier
`status`: Current status
`instagram_url`: Original Instagram URL
`created_at`: When task was created
`started_at`: When processing began (if started)
`completed_at`: When processing finished (if completed)
`expires_at`: When video file expires (if completed)
`downloaded`: Whether file has been downloaded (one-time access)
`error_message`: Error details (if failed)

URL Parameters

task_id: Parameter

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "completed", "created_at": "2024-01-01T00:00:00Z", "completed_at": "2024-01-01T00:00:30Z" }

GET /api/ig/download/{task_id}/file
FREE

Download Instagram video file (one-time access)
Download the processed Instagram video file. This endpoint provides one-time access only. After downloading, the file is automatically deleted from the server.
Files are available for 24 hours after processing
Each file can only be downloaded once
File is automatically deleted after download
Task status must be 'completed' before download
Binary video file with appropriate Content-Type
Content-Disposition header for filename
Supports MP4, MOV, AVI, WebM formats

URL Parameters

task_id: Parameter

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "completed", "result": { "data": "Task results here" } }

GET /api/ig/download/tasks
FREE

Get user's Instagram download tasks
Retrieve a paginated list of your Instagram download tasks. Tasks are ordered by creation date (newest first).
`limit`: Maximum number of tasks to return (default: 50, max: 100)
`offset`: Number of tasks to skip for pagination (default: 0)
`tasks`: Array of task objects with full details
`total`: Total number of tasks for the user
`limit`: Applied limit value
`offset`: Applied offset value
`task_id`: Unique task identifier
`status`: Current status (pending, processing, completed, failed)
`instagram_url`: Original Instagram URL
`created_at`: Task creation timestamp
`started_at`: Processing start time (if applicable)
`completed_at`: Processing completion time (if applicable)
`expires_at`: File expiration time (if completed)
`downloaded`: Whether file has been downloaded
`error_message`: Error details (if failed)

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "completed", "result": { "data": "Task results here" } }

POST /api/ig/download/profile-avatar
1 request

Create Instagram HD profile avatar download task
This endpoint creates a background task to download HD profile avatars from Instagram. The download is processed asynchronously and the image is available for 24 hours.
Cost: 1 request per download
Profile URLs: `instagram.com/username` (downloads HD avatar)
`task_id`: Unique identifier for tracking the download
`status`: Current task status (pending, processing, completed, failed)
`instagram_url`: The original Instagram URL
`created_at`: Task creation timestamp
`message`: Status message
Use `/ig/download/profile-avatar/{task_id}/status` to check progress
When status is 'completed', use `/ig/download/profile-avatar/{task_id}/file` to download

Request Body

{"example": "request"}

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "pending", "message": "Task created successfully" }

GET /api/ig/download/profile-avatar/{task_id}/status
FREE

Get Instagram image download task status
`pending`: Task is queued for processing
`processing`: Image is being downloaded
`completed`: Image is ready for download
`failed`: Download failed (check error_message)
`task_id`: Task identifier
`status`: Current status
`instagram_url`: Original Instagram URL
`created_at`: When task was created
`started_at`: When processing began (if started)
`completed_at`: When processing finished (if completed)
`expires_at`: When image file expires (if completed)
`downloaded`: Whether file has been downloaded (one-time access)
`image_width`: Image width in pixels (if completed)
`image_height`: Image height in pixels (if completed)
`file_size`: File size in bytes (if completed)
`error_message`: Error details (if failed)

URL Parameters

task_id: Parameter

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "completed", "created_at": "2024-01-01T00:00:00Z", "completed_at": "2024-01-01T00:00:30Z" }

GET /api/ig/download/profile-avatar/{task_id}/file
FREE

Download Instagram HD image file (one-time access)
Download the processed Instagram HD image file. This endpoint provides one-time access only. After downloading, the file is automatically deleted from the server.
Files are available for 24 hours after processing
Each file can only be downloaded once
File is automatically deleted after download
Task status must be 'completed' before download
Binary image file with appropriate Content-Type
Content-Disposition header for filename
Supports JPG, PNG, WEBP formats

URL Parameters

task_id: Parameter

Example Response

{ "task_id": "abc123-def456-ghi789", "status": "completed", "result": { "data": "Task results here" } }

GET /health
FREE

Health check endpoint to verify API status

Example Response

{ "success": true, "data": {} }