Sounds

Virlo collects audio/sound metadata from TikTok, YouTube, and Instagram videos. Use these endpoints to discover trending sounds, search by title, track adoption velocity, and find what sounds a creator owns.

Looking for a sound-specific deep dive? Satellite Sound Lookups → returns every video (TikTok) or reel (Instagram) using a specific sound, aggregate stats (views, engagement, velocity, top creators), and optional LLM-derived trends with time_windows, resurged, and momentum per trend. $0.50 base, $1.00 with trend_analysis=true. TikTok + Instagram (YouTube not supported).

Platform field availability varies by source. TikTok provides the richest data (title, duration, cover_url, usage_count, is_commerce_music, owner info).

Every sound carries two identifiers: id is Virlo's UUID — the one every /v1/sounds/:sound_id route expects — and external_id is the platform-native sound ID, which is what you need to build a link back to TikTok/Instagram or to reconcile against data you collected yourself. They are not interchangeable. YouTube provides title, cover_url, and owner info. Instagram provides title and owner_nickname only. Fields unavailable for a platform return null.

All video responses across the API (Digest, Orbit, Comet, Satellite, Tracking) now include an optional sound object — this is additive and non-breaking.

GET/v1/sounds/trending

Returns sounds currently trending in the Virlo dataset, ranked by recent dataset velocity.

The default sort videos_7d ranks by the number of videos published using each sound in the last 7 days — the recency-weighted "what is rising right now" signal. Use videos_30d to widen the window to 30 days. The legacy sorts usage_count and video_count rank by all-time totals (greatest hits, not "trending"); they remain available for callers asking reach-not-momentum questions.

Looking for sounds going from near-zero to viral in a single week? See Breakout sounds — the relative-momentum companion to this endpoint.

Each result is enriched with video_count and avg_views from our dataset; velocity sorts also include videos_in_window (the count that drove the ordering).

On the velocity sorts (and on Breakout), pagination.total is a running lower bound, not a grand total — drive pagination with has_next_page. See the Pagination guide.

Cost per request:$0.25

Query parameters

Name
platform
Type
string
Description
Filter by platform: tiktok, youtube, or instagram.
Name
sort
Type
string
Description
Sort mode. Default videos_7d (recent velocity). Options:
- videos_7d — videos using this sound in the last 7 days (default, real trending)
- videos_30d — videos using this sound in the last 30 days
- usage_count — all-time platform-wide usage (legacy, greatest hits)
- video_count — all-time video count in our dataset (legacy)
Name
commerce_only
Type
boolean
Description
Set to true to filter to TikTok commerce-safe music only.
Name
limit
Type
number
Description
Results per page (1-100). Default is 20.
Name
page
Type
number
Description
Page number. Default is 1.

Request

GET

/v1/sounds/trending

curl -G https://api.virlo.ai/v1/sounds/trending \
  -H "Authorization: Bearer {token}" \
  -d platform=tiktok \
  -d sort=videos_7d \
  -d limit=20

Response

{
  "data": [
    {
      "id": "8f6e5c50-1451-4007-a120-92744e632dad",
      "external_id": "7247344660485146625",
      "title": "Saxophones getting louder",
      "platform": "tiktok",
      "duration": 27,
      "cover_url": "...",
      "owner_handle": null,
      "owner_nickname": "BCD Studio",
      "is_original": false,
      "is_commerce_music": true,
      "usage_count": 138106,
      "video_count": 50,
      "avg_views": 612000,
      "videos_in_window": 50
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 21,
    "total_pages": 2,
    "has_next_page": true,
    "has_prev_page": false
  },
  "sort": "videos_7d"
}

GET/v1/sounds/breakout

Breakout sounds

Returns sounds with the highest recent-burst ratio — rapidly rising from a small baseline. This is the relative-momentum companion to Trending sounds:

Trending favours sounds with the largest absolute weekly volume (e.g. a mature sound still gaining 100 videos/week).
Breakout favours sounds where almost all of the activity happened in the last 7 days (e.g. a sound that went from near-zero to 40 videos in one week).

Results are ranked by acceleration = (videos_7d + 1) / (prior_weekly + 1), where prior_weekly is the average videos/week over the prior 4 weeks (days 8–35). An acceleration: 20.0 sound is being used 20× faster than its prior-month rate — a true breakout off a small base. The legacy burst_ratio and breakout_score fields are still returned for backward compatibility. Use min_recent and min_baseline to tune the noise floor.

Cost per request:$0.25

Query parameters

Name
platform
Type
string
Description
Filter by platform: tiktok, youtube, or instagram.
Name
commerce_only
Type
boolean
Description
Set to true to filter to TikTok commerce-safe music only.
Name
min_recent
Type
number
Description
Minimum videos in the last 7 days for a sound to qualify. Default 3. Filters out one-hit wonders.
Name
min_baseline
Type
number
Description
Minimum videos over the 90-day baseline window. Default 3. Filters out brand-new-to-dataset sounds we just discovered.
Name
limit
Type
number
Description
Results per page (1-100). Default is 20.
Name
page
Type
number
Description
Page number. Default is 1.

Request

GET

/v1/sounds/breakout

curl -G https://api.virlo.ai/v1/sounds/breakout \
  -H "Authorization: Bearer {token}" \
  -d platform=tiktok \
  -d limit=20

Response

{
  "data": [
    {
      "id": "8f6e5c50-1451-4007-a120-92744e632dad",
      "title": "BOOMPALA",
      "platform": "tiktok",
      "duration": 18,
      "cover_url": "...",
      "owner_handle": null,
      "owner_nickname": null,
      "is_original": false,
      "is_commerce_music": false,
      "usage_count": 59490,
      "videos_7d": 42,
      "videos_30d": 47,
      "videos_90d": 47,
      "burst_ratio": 0.8936,
      "breakout_score": 37.5319,
      "prior_weekly": 1.75,
      "acceleration": 20.0
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 21,
    "total_pages": 2,
    "has_next_page": true,
    "has_prev_page": false
  }
}

GET/v1/sounds/search

Search sounds

Search sounds by title keyword with fuzzy matching (powered by PostgreSQL trigram indexes). Coverage grows daily as our dataset expands.

Cost per request:$0.10

Query parameters

Name
q
Type
string
Required
*
Description
Search query (minimum 2 characters). Fuzzy-matched against sound titles.
Name
platform
Type
string
Description
Filter by platform: tiktok, youtube, or instagram.
Name
limit
Type
number
Description
Results per page (1-100). Default is 20.
Name
page
Type
number
Description
Page number. Default is 1.

Request

GET

/v1/sounds/search

curl -G https://api.virlo.ai/v1/sounds/search \
  -H "Authorization: Bearer {token}" \
  -d q=lofi+beats \
  -d platform=tiktok \
  -d limit=20

Response

{
  "data": [
    {
      "id": "90121d92-ce97-47cd-a1ee-8bc2bb9d6734",
      "title": "Original Sound",
      "platform": "tiktok",
      "duration": 15,
      "cover_url": "dc58b38b-6876-4d48-b64c-6a69e960e477.jpg",
      "owner_handle": null,
      "owner_nickname": null,
      "is_original": false,
      "is_commerce_music": false,
      "usage_count": 1078950
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3310,
    "total_pages": 166,
    "has_next_page": true,
    "has_prev_page": false
  }
}

When fewer than 5 results are found, a note field is returned with a message suggesting broader search terms. This advisory disappears as dataset coverage grows.

GET/v1/sounds/:sound_id

Sound details

Returns full sound metadata plus aggregate statistics: total videos in our dataset, average views, and the top-performing video URL. The response always includes a track_resolution object that maps the sound to its canonical recording — ISRC, DSP track/artist identifiers, release status, and the recording's artist.

Cost per request:$0.05

Resolution is lazy: until a sound has been resolved, track_resolution.status is "unresolved". Pass resolve=true to trigger an on-demand match — this adds the sound_artist_resolution feature cost ($0.10) the first time a sound is resolved. Re-reads of an already-resolved sound are free even with resolve=true.

Resolution runs a tiered, multi-source fallback chain (free ISRC registries first, paid audio-fingerprint / web-search tiers only on a miss) so coverage doesn't depend on any single provider and survives Spotify API changes. Beyond the artist + ISRC, it reports release_status:

released — a verified ISRC was found in a catalogue/registry.
unreleased — the recording was identified but is absent from every DSP/ISRC source (a TikTok "ID", teaser, leak, or pre-release that has no distributor ISRC yet).
unknown — could not determine.

resolution_source names the tier that produced the answer, and release_date is included when a source supplies one.

Path parameters

Name
sound_id
Type
string
Required
*
Description
The sound UUID.

Query parameters

Name
resolve
Type
boolean
Description
When true, resolve the sound to its canonical recording (Spotify track match → ISRC + DSP IDs + artist) if it isn't already resolved. Adds the sound_artist_resolution cost ($0.10) only on a fresh resolution. Default false.

Request

GET

/v1/sounds/:sound_id

curl -G https://api.virlo.ai/v1/sounds/8f6e5c50-1451-4007-a120-92744e632dad \
  -H "Authorization: Bearer {token}" \
  -d resolve=true

Response

{
  "data": {
    "id": "8f6e5c50-1451-4007-a120-92744e632dad",
    "title": "I'll Never Let You Go",
    "platform": "tiktok",
    "duration": 62,
    "cover_url": "31ec36a6-6eea-408f-9cc8-4657e4b3994f.jpg",
    "owner_handle": null,
    "owner_nickname": null,
    "is_original": false,
    "is_commerce_music": true,
    "usage_count": 63476335,
    "total_videos": 26,
    "avg_views": 79593,
    "top_video_url": "https://www.tiktok.com/@krasikovalexey/video/7625684128121343246",
    "track_resolution": {
      "status": "resolved",
      "artist_name": "Sarah Kang",
      "isrc": "USXXX2200001",
      "spotify_track_id": "3n3Ppam7vgaVa1iaRUc9Lp",
      "spotify_artist_id": "1uNFoZAHBGtllmzznpCI3s",
      "apple_music_id": null,
      "release_status": "released",
      "resolution_source": "deezer",
      "release_date": "2022-03-04",
      "confidence": 0.91,
      "resolved_at": "2026-06-24T18:00:00Z"
    }
  }
}

GET/v1/sounds/:sound_id/videos

Sound videos

Returns videos that use a specific sound, with full video metadata and author information.

Cost per request:$0.25

Path parameters

Name
sound_id
Type
string
Required
*
Description
The sound UUID.

Query parameters

Name
sort
Type
string
Description
Sort by views_desc (default) or publish_date_desc.
Name
platform
Type
string
Description
Filter by platform: tiktok, youtube, or instagram.
Name
limit
Type
number
Description
Results per page (1-100). Default is 20.
Name
page
Type
number
Description
Page number. Default is 1.

Request

GET

/v1/sounds/:sound_id/videos

curl -G https://api.virlo.ai/v1/sounds/8f6e5c50-1451-4007-a120-92744e632dad/videos \
  -H "Authorization: Bearer {token}" \
  -d sort=views_desc \
  -d limit=20

Response

{
  "data": [
    {
      "id": "68d60995-49de-42fa-9648-25ac28c1094f",
      "url": "https://www.tiktok.com/@krasikovalexey/video/7625684128121343246",
      "description": "When the beat drops #fyp #dance",
      "platform": "tiktok",
      "views": 1127436,
      "likes": 59934,
      "shares": 16150,
      "comments": 579,
      "bookmarks": 8222,
      "publish_date": "2026-04-06T16:29:51",
      "hashtags": ["fyp", "dance"],
      "thumbnail_url": "6adfcdd1-bb6a-431f-888f-cd3f7a9c53c7.jpg",
      "is_duet": null,
      "is_stitch": null,
      "author": {
        "username": "krasikovalexey",
        "verified": false,
        "followers": 2165,
        "avatar_url": "62fc6559-eae8-46f7-8b00-0e68cc8b860e.heic"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 26,
    "total_pages": 2,
    "has_next_page": true,
    "has_prev_page": false
  }
}

GET/v1/sounds/:sound_id/usage-history

Usage history

Returns a daily time-series of a sound's usage_count (platform-reported) and video_count_local (videos in Virlo's dataset), along with delta fields for tracking acceleration. Snapshots are taken daily at 2 AM UTC.

Cost per request:$0.05

Path parameters

Name
sound_id
Type
string
Required
*
Description
The sound UUID.

Query parameters

Name
start_date
Type
string
Description
Start date (YYYY-MM-DD). Optional.
Name
end_date
Type
string
Description
End date (YYYY-MM-DD). Optional.
Name
limit
Type
number
Description
Maximum snapshots to return (1-365). Default is 90.

Request

GET

/v1/sounds/:sound_id/usage-history

curl -G https://api.virlo.ai/v1/sounds/8f6e5c50-1451-4007-a120-92744e632dad/usage-history \
  -H "Authorization: Bearer {token}" \
  -d start_date=2026-04-01 \
  -d end_date=2026-04-22 \
  -d limit=90

Response

{
  "data": [
    {
      "usage_count": 5800000,
      "video_count_local": 110,
      "delta_usage_count": null,
      "delta_video_count_local": null,
      "snapshot_at": "2026-04-15T02:00:00.000Z"
    },
    {
      "usage_count": 5920000,
      "video_count_local": 120,
      "delta_usage_count": 120000,
      "delta_video_count_local": 10,
      "snapshot_at": "2026-04-16T02:00:00.000Z"
    }
  ]
}

The first snapshot in a series always has null delta fields since there is no prior snapshot to compare against. Delta values represent the change from the previous day's snapshot.

GET/v1/sounds/by-creator/:platform/:handle

Creator sounds

Returns all sounds owned by a specific creator or artist, with per-sound UGC metrics and aggregate totals. Useful for music industry clients tracking artist sound adoption.

Matching covers the platform handle, the display name (owner_nickname, case-insensitive — e.g. Atomica Music), and the resolved artist name from sound→artist resolution, so artist catalogs aggregate even when individual sounds are missing a platform handle. URL-encode spaces in display names (Atomica%20Music).

When a handle matches no sound identity fields directly (platforms often attribute sounds only by display name), the handle is automatically resolved to the creator's display name and the lookup retried — so kygomusic and Kygo return the same catalog.

Cost per request:$0.25

Path parameters

Name
platform
Type
string
Required
*
Description
Creator platform: tiktok, youtube, or instagram.
Name
handle
Type
string
Required
*
Description
Creator handle (with or without @ prefix).

Query parameters

Name
sort
Type
string
Description
Sort by usage_count (default) or video_count.
Name
limit
Type
number
Description
Results per page (1-100). Default is 20.
Name
page
Type
number
Description
Page number. Default is 1.

Request

GET

/v1/sounds/by-creator/:platform/:handle

curl -G https://api.virlo.ai/v1/sounds/by-creator/tiktok/artist_name \
  -H "Authorization: Bearer {token}" \
  -d sort=usage_count \
  -d limit=20

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My Original Sound",
      "platform": "tiktok",
      "duration": 30,
      "cover_url": "sound-cover-3.webp",
      "owner_handle": "@artist_name",
      "owner_nickname": "Artist Name",
      "is_original": true,
      "is_commerce_music": false,
      "usage_count": 1500000,
      "video_count": 45,
      "avg_views": 280000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "total_pages": 1,
    "has_next_page": false,
    "has_prev_page": false
  },
  "aggregates": {
    "total_sounds": 3,
    "total_ugc_videos": 128,
    "total_usage_count": 4500000
  }
}

GET/v1/agents/:agent_id/sounds

Agent sounds

Returns the top sounds found within a Content Research Agent run. Free. Sort by run-over-run momentum (rising / growth_7d); rows carry growth fields + a lifecycle label. Prefer this over legacy Orbit/Comet aliases (below).

Path parameters

Name
agent_id
Type
string
Required
*
Description
The Content Research Agent UUID.

Query parameters

Name
sort
Type
string
Description
Ranking mode. Options: video_count (default — # videos in the agent's results using each sound), usage_count (platform-wide all-time usage), rising / growth_7d (run-over-run growth — the momentum signal that surfaces sounds breaking out right now).
Name
limit
Type
number
Description
Results per page (1-100). Default is 20.
Name
page
Type
number
Description
Page number. Default is 1.

Each sound carries additive momentum fields: growth_video_count and growth_views (change since the previous run; null on first observation) and a lifecycle label (new / rising / steady / fading). Pivot to /v1/sounds/:sound_id/usage-history for the full time-series of any sound by its id. Responses use the pagination-object shape.

Request

GET

/v1/agents/:agent_id/sounds

curl -G https://api.virlo.ai/v1/agents/2b1f9c3d-7c4e-4d8a-9f12-6e8b4a2c1d05/sounds \
  -H "Authorization: Bearer {token}" \
  -d sort=rising \
  -d limit=20

Response

{
  "data": [
    {
      "id": "48d51fe9-8932-4d86-becb-39ff204275ef",
      "title": "EVERYTHING HALLELUJAH",
      "platform": "tiktok",
      "duration": 60,
      "cover_url": "e79043d9-ac83-4106-b74f-613ebae48883.jpg",
      "owner_handle": null,
      "owner_nickname": null,
      "is_original": false,
      "is_commerce_music": true,
      "usage_count": 212402,
      "video_count": 4,
      "avg_views": 8765,
      "growth_video_count": 3,
      "growth_views": 24180,
      "lifecycle": "rising"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 15,
    "total_pages": 1,
    "has_next_page": false,
    "has_prev_page": false
  }
}

Legacy Orbit / Comet sounds

GET /v1/orbit/:id/sounds and GET /v1/comet/:id/sounds are deprecated aliases of Agent sounds. Same response shape. Prefer GET /v1/agents/:id/sounds. See Orbit / Comet stubs (removed August 3, 2026).