Virlo

Deep-dive lookup

Sound lookup

See who uses a TikTok or Instagram sound, which hashtags go with it, and how those videos perform. Add trend analysis to see the creative formats people make with it.

At a glance
What it does
Pulls a fresh sample of the videos using one sound, straight from the app. Stats describe that sample, not every video ever made with the sound.
You send
The platform (tiktok or instagram) and the sound's ID from its link.
You get back
A job ID right away, then the sound, its videos (50 by default, about 300 with trend analysis), and stats.
Cost
$0.50 per lookup, or $1.00 with trend analysis. Checking progress and reopening results are free.
How long
Under 1.5 minutes, about 2 with trend analysis. Up to several minutes when busy.
Use it when
You need fresh data on one sound. For videos Virlo already has, Sound videos is cheaper at $0.25.

TikTok and Instagram only. YouTube doesn't list videos per sound, so the youtube platform, or a YouTube sound ID Virlo already knows, is rejected at no charge.

Instagram shares less: share and save counts, duet and stitch flags, video country, and the sound's total uses come back as 0, false, or null. Instagram views include Facebook plays.

GET/v1/satellite/sounds/:platform/:music_id

Start a sound lookup

Starts the lookup and returns a job_id right away. Send it to Check lookup status for the results.

Cost per request:$0.50

With trend analysis: $1.00.

Repeats within 6 hours are free. Asking for the same sound within 6 hours of a finished lookup returns the saved result, marked cached: true. Watch out:

  • Adding trend analysis to a lookup that ran without it starts a fresh $1.00 lookup.
  • Repeating a lookup that is still running starts a second, billed lookup. Keep checking the first job_id.
  • A different max_videos still returns the saved result as it was.
  • After 6 hours, a new lookup is billed and saved as a new run. Older runs stay.

Path parameters

  • Name
    platform
    Type
    string
    Required
    *
    Description

    tiktok or instagram (lowercase).

  • Name
    music_id
    Type
    string
    Required
    *
    Description

    The number at the end of the sound's link, such as 7392134672372746241 in tiktok.com/music/morning-coffee-7392134672372746241 or instagram.com/reels/audio/<id>. From Virlo's sound endpoints, use external_id or id. An ID Virlo hasn't seen is looked up as-is and billed, so double-check it.

Query parameters

  • Name
    trend_analysis
    Type
    string
    Description

    true adds trend analysis for $0.50 more and keeps every video found (usually about 300, up to 500), ignoring max_videos. Only true or 1 turn it on; True or yes count as off. The extra $0.50 is refunded if no trends come out.

  • Name
    max_videos
    Type
    integer
    Description

    Videos to keep and analyze, 1 to 100 (default 50): the first ones in the platform's order, not the most viewed. Fewer is not faster or cheaper. Ignored with trend analysis.

Request

GET
/v1/satellite/sounds/:platform/:music_id
curl -G https://api.virlo.ai/v1/satellite/sounds/tiktok/7392134672372746241 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d trend_analysis=true

Response

{
  "data": {
    "job_id": "b5a1c328-53d6-46fe-b33b-d2d757e465d9",
    "status": "processing"
  }
}
GET/v1/satellite/sounds/status/:job_id

Check lookup status

Send the job_id to check progress, for free. Check again every 10 to 15 seconds (polling) until status is completed (data in result) or failed (reason in error). To skip polling, listen for the satellite.lookup.completed webhook with data.type "sound_lookup".

Still processing after 15 minutes? It has likely stalled, so start again (billed as new). Don't wait: the saved run says failed only after 3 hours, and isn't refunded.

What's in the result

  • Name
    run_id
    Type
    string
    Description

    Same as job_id. Reopen the result with it for free.

  • Name
    sound
    Type
    object
    Description

    title, duration_seconds, cover_url, owner (handle and nickname, either may be null), is_original (a creator's own audio), is_commerce_music, and reported_usage_count (TikTok's count of videos using it).

  • Name
    stats
    Type
    object
    Description

    See Stats.

  • Name
    trends
    Type
    object
    Description

    analyzed: false unless you asked for trend analysis.

  • Name
    videos
    Type
    array
    Description

    The videos kept, in the platform's order, not by views.

Full field reference

Each videos[] item and stats.top_video has:

  • Name
    id / url / description
    Type
    string
    Description

    Platform ID, link, and caption.

  • Name
    hashtags
    Type
    string[]
    Description

    Caption hashtags, lowercase, without #.

  • Name
    publish_date / duration_seconds
    Type
    string / number
    Description

    Post time (UTC) and length in seconds.

  • Name
    views / likes / comments / shares / collects
    Type
    number
    Description

    collects means saves.

  • Name
    is_duet / is_stitch / region
    Type
    boolean / string
    Description

    TikTok duet and stitch flags, and a country code such as US.

  • Name
    author
    Type
    object
    Description

    unique_id (handle), nickname, is_verified, and follower_count (currently always null).

Request

GET
/v1/satellite/sounds/status/:job_id
curl https://api.virlo.ai/v1/satellite/sounds/status/b5a1c328-53d6-46fe-b33b-d2d757e465d9 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

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

Stats

Plain math over the videos in videos[], with no AI.

  • Name
    videos_analyzed
    Type
    number
    Description

    How many videos the stats cover.

  • Name
    views
    Type
    object
    Description

    total, avg, median, max, and min.

  • Name
    engagement
    Type
    object
    Description

    Totals and averages for likes, comments, shares, and collects. engagement_rate is (likes + comments + shares + collects) / views, as a fraction (0.0919 = 9.19%).

  • Name
    velocity
    Type
    object
    Description

    videos_per_week: sampled videos per week (2026-W38, weeks start Monday UTC), oldest first, for the 26 most recent weeks that had videos (empty weeks are skipped). For a big sound it shows the sample, not the sound's true pace. last_4w_avg_videos_per_week and prior_4w_avg_videos_per_week average the 4 newest listed weeks and the 4 before. is_accelerating is true if the newer average is 15%+ higher, or if there is nothing earlier to compare, so a sound whose videos all fall in 4 or fewer weeks, like a brand-new one, always reads true.

  • Name
    top_creators
    Type
    array
    Description

    Up to 10 creators by total views, with video_count, total_views, and avg_views.

With trend_analysis=true, an AI reads up to 240 videos, favoring the most viewed and at most 6 per creator where it can. It uses captions, hashtags, lengths, dates, and stats (it doesn't watch the videos) to group them into named creative patterns, with tactics a creator could copy.

Dates, counts, and view totals come from each pattern's real videos, so the AI can't invent them. The summary, descriptions, and confidence score are the AI's own. Each trend shows when it ran, whether it came back, and whether views grew.

Full field reference
  • Name
    status
    Type
    string
    Description

    ok, insufficient_corpus (under 10 videos, no trends, trend fee refunded), or skipped (not requested). If the AI step fails, status is still ok with empty summary and trends, and the trend fee is refunded (credits_refunded on the result).

  • Name
    summary
    Type
    string
    Description

    A short overview in the AI's words, counting only the videos it read.

  • Name
    trends[].name / description / tactics
    Type
    string / string[]
    Description

    Label, description, and things a creator could copy.

  • Name
    trends[].confidence
    Type
    number
    Description

    The AI's own score from 0 to 1.

  • Name
    trends[].video_count / evidence_video_ids
    Type
    number / string[]
    Description

    How many videos show the pattern, and their IDs. Every ID is in videos[].

  • Name
    trends[].time_windows
    Type
    array
    Description

    Date ranges when the pattern ran, each with start_date, end_date, video_count, view, like, comment, and share totals, avg_views, and a description. A sample spanning under 14 days gives one window.

  • Name
    trends[].resurged
    Type
    boolean
    Description

    true with two or more windows (it faded and came back).

  • Name
    trends[].momentum
    Type
    string | null
    Description

    Latest window's average views against the one before: stronger (15%+ higher), weaker (15%+ lower), or similar. null with one window.

Re-read past runs

Every lookup is saved as a run under its job_id (called run_id here). Reopening is free, any time:

  • GET /v1/satellite/runs/:run_id: the full result.
  • GET /v1/satellite/runs?type=sound_lookup&platform=tiktok: your past sound lookups.
  • GET /v1/satellite/runs/:run_id/videos?limit=50&offset=0: the videos, a page at a time (25 per page by default, up to 200).

Each paid lookup of a sound gets its own run_id. A newer lookup never overwrites an older run, so every result you paid for stays readable. More in Re-read past runs.

Errors

Rejected requests cost nothing. A started lookup is billed, and refunded in full if it ends failed.

  • Name
    400 Bad Request
    Description

    Platform not tiktok or instagram, a YouTube sound ID Virlo recognizes, an unknown Virlo id (UUID), empty music_id, max_videos outside 1 to 100, or an unknown query parameter.

  • Name
    401 Unauthorized
    Description

    Key missing (missing_api_key), or wrong or revoked (invalid_api_key). See Authentication.

  • Name
    402 Payment Required
    Description

    Balance under $0.50, or under $1.00 with trend analysis. required_credits is in credits (100 = $1.00). Below $0.50 it asks for $0.50 (required_credits: 50) even for a trend lookup. Free repeats need this balance too.

  • Name
    404 Not Found
    Description

    Status check: job ID unknown or over 24 hours old. Open the saved run instead.

  • Name
    429 Too Many Requests
    Description

    Daily request limit reached. See Rate limits.

Was this page helpful?