Satellite

Start a sound lookup job (TikTok or Instagram)

Queues a deep-dive lookup for every video/reel using the given sound. Supported platforms: tiktok and instagram. (YouTube is not supported — there is no public "videos using this sound" feed for YouTube.) Returns a job_id immediately. Poll GET /v1/satellite/sounds/status/:job_id for results. The completed result includes the full normalized video list, aggregated stats, and (when trend_analysis=true) an LLM-derived trends block. Each completed job is also persisted as a durable satellite_run that can be re-read for free indefinitely via /v1/satellite/runs/:run_id. Pricing: $0.50 base + $0.50 surcharge when trend_analysis=true. Refunds: a lookup that fails is refunded in full, and the trend_analysis surcharge is refunded when no trends come out (fewer than 10 videos, or the analysis step failed). The amount is reported as credits_refunded.

get/v1/satellite/sounds/{platform}/{music_id}

Request

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

Path parameters

platform'tiktok' | 'instagram' required

Platform — "tiktok" or "instagram" (YouTube is not supported)

music_idstring required

The sound's platform-native id — its external_id (NOT the id UUID). For TikTok this is the music/clip id; for Instagram it is the audio id (audio_cluster_id). Get it from the external_id field on any /v1/sounds, /v1/orbit/:id/sounds, or /v1/comet/:id/sounds result. As a convenience you may also pass a Virlo sound UUID and we will resolve it to the right platform automatically. If the id belongs to an unsupported platform (e.g. YouTube) the request returns 400 and is not charged.

Query parameters

trend_analysisboolean
Example:true

When true, runs the LLM-based trend analysis. Forces a deeper fetch (~300 videos) and ignores any max_videos value the caller passed. Adds a $0.50 surcharge on top of the $0.50 base. Trends are derived from real publish dates — no LLM date hallucination is possible. Set false (default) to skip trend analysis and only return stats.

max_videosnumber
Example:50

Number of videos to fetch and analyze. Ignored when trend_analysis=true (we then target ~300 videos automatically). Default 50.

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.