Virlo

Satellite - Creator Lookup

Look up any creator by platform and username. 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.

GET/v1/satellite/creator/:platform/:username

Start Creator Lookup

Queue a creator lookup job. The endpoint returns immediately with a job_id that you use to poll for results. All heavy work (fetching videos, computing stats) happens in the background.

Cost per request:

Path parameters

  • Name
    platform
    Type
    string
    Required
    *
    Description

    Social media platform. One of: youtube, tiktok, instagram

  • Name
    username
    Type
    string
    Required
    *
    Description

    Creator's handle (with or without leading @). Example: mkbhd, khaby.lame, therock

Query parameters

  • Name
    include
    Type
    string
    Description

    Comma-separated optional sections to include in the response: videos, outliers. Example: include=videos,outliers

  • Name
    max_videos
    Type
    integer
    Description

    Number of videos to fetch and analyze (1-100). Default is 20. More videos = better stats but slower response.

  • Name
    outlier_threshold
    Type
    number
    Description

    Multiplier for outlier detection. A video is an outlier when views > median_views * threshold. Default is 2.0. Only relevant when include=outliers.

Request

GET
/v1/satellite/creator/:platform/:username
curl -G https://api.virlo.ai/v1/satellite/creator/tiktok/khaby.lame \
  -H "Authorization: Bearer {token}" \
  -d include=videos,outliers \
  -d max_videos=30 \
  -d outlier_threshold=2.5

Response

{
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "processing"
  }
}
GET/v1/satellite/creator/status/:job_id

Poll Lookup Status

Poll for the results of a creator lookup job. Returns processing while the job is running, and the full creator data 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 the full creator data:

  • Name
    username
    Type
    string
    Description

    The looked-up username.

  • Name
    platform
    Type
    string
    Description

    The platform queried.

  • Name
    profile
    Type
    CreatorProfile
    Description

    Creator's profile data. Omitted if the profile API call fails.

  • Name
    stats
    Type
    CreatorStats
    Description

    Computed statistics from analyzed videos.

  • Name
    hashtags
    Type
    HashtagStats[]
    Description

    Top 10 hashtags by total views (descending).

  • Name
    videos
    Type
    CreatorVideo[]
    Description

    Only present when include=videos was specified.

  • Name
    outliers
    Type
    OutliersResponse
    Description

    Only present when include=outliers was specified.

CreatorProfile

Unified across all platforms. Fields unavailable for a given platform return null.

  • Name
    followers
    Type
    number
    Description

    Follower/subscriber count.

  • Name
    following
    Type
    number
    Description

    Following count (0 for YouTube).

  • Name
    avatar_url
    Type
    string | null
    Description

    Profile picture URL.

  • Name
    url
    Type
    string
    Description

    Full profile URL.

  • Name
    description
    Type
    string | null
    Description

    Bio/description.

  • Name
    is_verified
    Type
    boolean | null
    Description

    Verified badge status.

  • Name
    total_videos
    Type
    number | null
    Description

    Total video count on the account.

  • Name
    total_likes
    Type
    number | null
    Description

    Total likes received (TikTok only).

  • Name
    total_views
    Type
    number | null
    Description

    Total channel views (YouTube only).

  • Name
    total_posts
    Type
    number | null
    Description

    Total posts/media count (Instagram only).

CreatorStats

Computed from the fetched videos.

  • Name
    videos_analyzed
    Type
    number
    Description

    Number of videos used to compute stats.

  • Name
    avg_views
    Type
    number
    Description

    Mean view count.

  • Name
    median_views
    Type
    number
    Description

    Median view count.

  • Name
    avg_likes
    Type
    number
    Description

    Mean like count.

  • Name
    avg_comments
    Type
    number
    Description

    Mean comment count.

  • Name
    engagement_rate
    Type
    number
    Description

    (total_likes + total_comments) / total_views, rounded to 2 decimals.

  • Name
    top_performing_views
    Type
    number
    Description

    Highest view count among analyzed videos.

  • Name
    lowest_performing_views
    Type
    number
    Description

    Lowest view count among analyzed videos.

  • Name
    posting_frequency_days
    Type
    number | undefined
    Description

    Average days between posts. Only present if 2+ videos have publish dates.

HashtagStats

Top 10 hashtags sorted by total_views descending. Normalized to lowercase.

  • Name
    hashtag
    Type
    string
    Description

    The hashtag (lowercase, without #).

  • Name
    total_views
    Type
    number
    Description

    Sum of views across all videos using this hashtag.

  • Name
    avg_views
    Type
    number
    Description

    Average views per video using this hashtag.

  • Name
    avg_likes
    Type
    number
    Description

    Average likes per video using this hashtag.

  • Name
    avg_comments
    Type
    number
    Description

    Average comments per video using this hashtag.

  • Name
    used_count
    Type
    number
    Description

    Number of videos that used this hashtag.

CreatorVideo

Returned in the videos array when include=videos.

  • Name
    id
    Type
    string
    Description

    Platform-specific video ID.

  • Name
    title
    Type
    string
    Description

    Video title or caption.

  • Name
    description
    Type
    string
    Description

    Video description.

  • Name
    views
    Type
    number
    Description

    View count.

  • Name
    likes
    Type
    number
    Description

    Like count.

  • Name
    comments
    Type
    number
    Description

    Comment count.

  • Name
    publishDate
    Type
    string | null
    Description

    ISO 8601 date string, or null if unavailable.

  • Name
    url
    Type
    string
    Description

    Direct URL to the video.

  • Name
    hashtags
    Type
    string[]
    Description

    Hashtags extracted from title/description.

OutliersResponse

Returned when include=outliers. Identifies which of the creator's own videos significantly outperform their median.

  • Name
    threshold_multiplier
    Type
    number
    Description

    The multiplier used (default 2.0, or the outlier_threshold query param).

  • Name
    outlier_videos
    Type
    ContentOutlier[]
    Description

    Videos exceeding the threshold, sorted by outlier_ratio descending.

ContentOutlier

Same fields as CreatorVideo plus:

  • Name
    outlier_ratio
    Type
    number
    Description

    video_views / median_views, rounded to 2 decimals. E.g., 5.23 means 5.23x the median.

Request

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

Response

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

Error responses

The Satellite Creator Lookup endpoints may return the following error codes:

  • Name
    400 Bad Request
    Description

    Invalid parameters provided. Common causes include: Invalid platform (must be youtube, tiktok, or instagram), missing username, invalid max_videos (must be a positive integer), invalid outlier_threshold (must be a positive number), or no videos found for the given creator.

  • 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. Results expire after 24 hours.

Notes

  • The start endpoint returns within 1-2 seconds. All heavy work happens in the background.
  • Typical completion time: 5-40 seconds depending on platform and max_videos.
  • Results expire after 24 hours. Poll promptly after starting a job.
  • Response time scales with max_videos. Default (20) is fastest. Higher values require more pagination.
  • Instagram pagination is limited by what the API returns per page. Requesting max_videos=100 may return fewer if the creator has limited public reels.
  • Outlier detection compares a creator's videos against their own median. This is different from Comet's creator-outliers which compares creators against each other by follower/view ratio.
  • Hashtags are extracted from video titles and descriptions, normalized to lowercase and deduplicated. Only the top 10 by total views are returned.
  • Rate limits (5/min, 30/hour, 200/day) apply to the start endpoint. The status polling endpoint is not rate limited separately.

Was this page helpful?