Satellite - Video Outlier Analysis

Analyze a video's performance relative to its creator's other content. This endpoint uses an async polling pattern: submit a request, receive a job ID, then poll a status endpoint for results.

All Satellite V1 endpoints use the base URL https://api.virlo.ai/v1/satellite. All parameter names and response fields use snake_case. All responses are wrapped in a { "data": { ... } } envelope.

POST/v1/satellite/video-outlier

Start Video Outlier Analysis

Queue a video outlier analysis job. The endpoint returns immediately with a job_id that you use to poll for results. The API fetches the creator's recent videos (~100), computes statistical metrics, and determines whether the video is an outlier — all in the background.

Cost per request:

Rate limits

Window	Limit
Per minute	5
Per hour	30
Per day	200

Rate limits apply to this start endpoint. The status polling endpoint is not rate limited separately.

Body parameters

Name
url
Type
string
Required
*
Description
Full video URL. Must be a valid URL from a supported platform.
Name
platform
Type
string
Required
*
Description
Social media platform. One of: youtube, tiktok, instagram

Request

POST

/v1/satellite/video-outlier

curl -X POST https://api.virlo.ai/v1/satellite/video-outlier \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.instagram.com/reels/DVMBt9pE4ob/",
    "platform": "instagram"
  }'

Response

{
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "processing"
  }
}

GET/v1/satellite/video-outlier/status/:job_id

Poll Analysis Status

Poll for the results of a video outlier analysis job. Returns processing while the job is running, and the full analysis when completed.

Path parameters

Name
job_id
Type
string
Required
*
Description
The job ID returned from the start endpoint.

Response fields (when completed)

The result object contains three sub-objects:

Name
video
Type
object
Description
The target video's stats.
Name
creator
Type
object
Description
Creator's profile information.
Name
analysis
Type
object
Description
Statistical outlier metrics.

video

Name
url
Type
string
Description
The original video URL.
Name
title
Type
string
Description
Video title or caption.
Name
views
Type
number
Description
Total view count.
Name
likes
Type
number
Description
Total like count.
Name
comments
Type
number
Description
Total comment count.
Name
publishDate
Type
string
Description
ISO 8601 publish timestamp.

creator

Name
username
Type
string
Description
Creator's handle.
Name
platform
Type
string
Description
Platform name.
Name
profile
Type
object
Description
Creator profile details (followers, following, avatar_url, url, description, is_verified, total_videos, total_likes, total_views, total_posts). Fields unavailable for a given platform return null.

analysis

Name
videos_analyzed
Type
number
Description
Number of creator's recent videos used in the analysis.
Name
median_views
Type
number
Description
Median view count across analyzed videos.
Name
avg_views
Type
number
Description
Average view count across analyzed videos.
Name
outlier_score
Type
number
Description
Ratio of this video's views to the creator's median views.
Name
percentile
Type
number
Description
Percentile rank of this video among the creator's content (0-100).
Name
std_deviation
Type
number
Description
Standard deviation of views across analyzed videos.
Name
z_score
Type
number
Description
Z-score measuring how many standard deviations from the mean.
Name
performance_label
Type
string
Description
Human-readable label: "viral", "above_average", "average", or "below_average".

Request

GET

/v1/satellite/video-outlier/status/:job_id

curl https://api.virlo.ai/v1/satellite/video-outlier/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "status": "processing"
  }
}

Polling example

async function analyzeVideo(url: string, platform: string): Promise<VideoOutlierResult> {
  // 1. Start the job
  const { data } = await api.post('/v1/satellite/video-outlier', { url, platform });
  const jobId = data.job_id;

  // 2. Poll every 2s, up to 90s
  const maxAttempts = 45;
  for (let i = 0; i < maxAttempts; i++) {
    await new Promise(r => setTimeout(r, 2000));

    const { data: job } = await api.get(`/v1/satellite/video-outlier/status/${jobId}`);

    if (job.status === 'completed') return job.result;
    if (job.status === 'failed') throw new Error(job.error);
    // status === 'processing' → keep polling
  }

  throw new Error('Analysis timed out');
}

Error responses

The Video Outlier endpoints may return the following error codes:

Name
400 Bad Request
Description
Invalid parameters provided. Common causes include: invalid or missing URL, unsupported platform (must be youtube, tiktok, or instagram), or the video/creator could not be resolved.
Name
401 Unauthorized
Description
Missing or invalid API key. Ensure you're including your API key in the Authorization header.
Name
402 Payment Required
Description
Insufficient credits to complete the request. Top up your account at your dashboard.
Name
404 Not Found
Description
Job ID not found or expired. Video outlier results expire after 5 minutes in Redis.
Name
429 Too Many Requests
Description
Rate limit exceeded. Check the Retry-After header for when to retry. Limits: 5/min, 30/hour, 200/day.

Notes

The start endpoint returns within 1-2 seconds. All heavy work happens in the background.
Typical completion time: 10-40 seconds depending on platform (Instagram is slowest).
Results expire after 5 minutes in Redis. Poll promptly after starting a job.
The performance_label is derived from the outlier score: "viral" (score >= 5x median), "above_average" (>= 2x), "average" (>= 0.5x), or "below_average" (< 0.5x).
Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included on every response. The Retry-After header is only present on 429 responses.