Satellite

Start a creator lookup job

Queues a creator lookup for processing. Returns immediately with a job_id. Poll GET /v1/satellite/creator/status/:job_id for results. Pricing: $0.50 base. Optional surcharges — trend_analysis=true (+$0.50); data_intelligence=true (+$0.25) enriches each video with structured content intelligence and a grounded "what's working" analysis, retrievable on GET /v1/satellite/runs/:run_id once intelligence_status is "ready"; audience_demographics / audience_geography (+$0.50 for a fresh snapshot — the two flags share one snapshot and are never double-charged; a cached snapshot within freshness_days is free). Ceiling with every add-on: up to $1.75. Refunds: a lookup that fails (for example a handle with no public posts, or a run that stalls and is failed by the recovery sweep) is refunded in full, and a surcharge whose add-on produced nothing is refunded (trend_analysis that yields no trends, an audience snapshot that was already cached or already being built, data_intelligence on a creator with no posts to enrich or whose analysis failed). The amount is reported as credits_refunded on the completed result or the failed status, and on GET /v1/satellite/runs/:run_id. Cache: a repeat lookup of the same creator within 6 hours returns the earlier run free (cached: true, status "completed"), but only when that run covers every option this request asks for: each add-on and include flag it turns on, at least as many max_videos, and the same outlier_threshold. Anything else, such as trend_analysis=true after a plain lookup, runs fresh and is charged.

get/v1/satellite/creator/{platform}/{username}

Request

  • Base URL: https://api.virlo.ai
  • URL: https://api.virlo.ai/v1/satellite/creator/{platform}/{username}
  • Auth: HTTP bearer

Path parameters

platform'youtube' | 'tiktok' | 'instagram' required

The social media platform

usernamestring required

Creator's handle (with or without leading @)

Query parameters

includestring
Example:videos,outliers

Comma-separated list of optional fields to include: "videos", "outliers"

cross_linksboolean
Example:true

Enable cross-platform link discovery. Finds the same creator on other platforms (YouTube, TikTok, Instagram, Twitter/X, Spotify).

max_videosnumber
Example:20

Number of videos to fetch and analyze. More videos = better stats but slower response.

outlier_thresholdnumber
Example:2

Multiplier for outlier detection. A video is an outlier if views > median_views * threshold. Only applies when include=outliers.

audience_demographicsboolean
Example:true

Include inferred audience demographics (age + gender distributions). Returns a cached snapshot if one exists within freshness_days; otherwise dispatches an async snapshot job and returns { status: "processing", job_id } so you can poll via the dedicated audience endpoints, and adds an extra $0.50 surcharge on top of the base $0.50 creator-lookup cost. A cache hit within freshness_days is free. Off by default — only computed when explicitly requested.

audience_geographyboolean
Example:true

Include inferred audience geography (country + city distributions, with languages). Same caching and $0.50 surcharge behavior as audience_demographics — a cached snapshot within freshness_days is free. Off by default.

freshness_daysnumber
Example:30

Maximum age (in days) of an acceptable cached audience snapshot. Snapshots older than this trigger a new async job. Only relevant when audience_demographics or audience_geography is set.

trend_analysisboolean

Run AI trend detection over this creator's body of work. Forces a deep fetch (max_videos is bumped to 100) so the model has enough signal, implicitly includes the videos[] payload, and adds an extra $0.50 surcharge on top of the base $0.50 creator-lookup cost. Trends are persisted with the run, so re-reading via GET /v1/satellite/runs/{run_id} is free. Returns the same trends shape as sound lookups: mechanically-derived time_windows[], resurged flag, and momentum metric.

data_intelligenceboolean

Run Data Intelligence on this creator's videos — the same structured content analysis Virlo runs for Content Research Agents. Each analyzed video is enriched with its hook (opening line + type), content format, and visual treatment, and the run gets a grounded "what's working" analysis. Implicitly includes the videos[] payload (like trend_analysis) — the enrichment hangs off the video list, so you don't need include=videos. Enrichment runs ASYNCHRONOUSLY after the base lookup completes: poll status/:job_id for the base result, then re-read GET /v1/satellite/runs/:run_id — the analysis object and intelligence_status populate once processing finishes (typically 1-3 min). Adds an extra 25 credits ($0.25) on top of the base $0.50 creator-lookup cost. Off by default. A repeat lookup within 6 hours is served free from a cached run only when that run also had data_intelligence=true; otherwise it runs fresh and is charged.

contextstring
Example:which hooks and formats drive their most-viewed videos

Optional free-text statement of what you're trying to learn from this creator (max 600 chars), e.g. "which hooks drive their most-viewed videos". When data_intelligence is enabled it grounds the "what's working" analysis on your goal. Ignored without data_intelligence.

slideshow_sort'recent' | 'popular'
Example:popular

Which carousels get slide-captured + OCR'd when a creator has more slideshows than the per-run cap (100). "popular" (default) keeps the highest-engagement carousels; "recent" keeps the newest by publish date, so the latest carousels are guaranteed OCR'd even before they accrue engagement. Only meaningful with data_intelligence on carousel-heavy Instagram/TikTok creators. Note this is the CAPTURE selector; the read-side sort on GET /v1/satellite/runs/:run_id/videos only reorders what was already captured.

Response

Job queued successfully

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.