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 using a specific TikTok 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. Currently TikTok only.

Platform field availability varies by source. TikTok provides the richest data (title, duration, cover_url, usage_count, is_commerce_music, owner info). 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).

Cost per request:

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",
      "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": 20,
    "total_pages": 1,
    "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).

The score is videos_7d × (videos_7d / videos_90d). A sound with burst_ratio: 1.0 had 100% of its recent activity concentrated in the last week — a true breakout. Use min_recent and min_baseline to tune the noise floor.

Cost per request:

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
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 20,
    "total_pages": 1,
    "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:

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.

Cost per request:

Path parameters

Name
sound_id
Type
string
Required
*
Description
The sound UUID.

Request

GET

/v1/sounds/:sound_id

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

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"
  }
}

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:

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:

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, with per-sound UGC metrics and aggregate totals. Useful for music industry clients tracking artist sound adoption.

Cost per request:

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/orbit/:orbit_id/sounds

Orbit sounds

Returns the top sounds found within an Orbit keyword search, aggregated from the videos in that search. Free — no credit charge.

Path parameters

Name
orbit_id
Type
string
Required
*
Description
The Orbit search UUID.

Query parameters

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/orbit/:orbit_id/sounds

curl -G https://api.virlo.ai/v1/orbit/f45339ef-2ba8-4ceb-9b86-4175442f9291/sounds \
  -H "Authorization: Bearer {token}" \
  -d limit=20

Response

{
  "data": [
    {
      "id": "13c48707-43d1-4075-9ce9-db664c4d1661",
      "external_id": "7559312683885201425",
      "title": "Walking Around - Instrumental Version",
      "platform": "tiktok",
      "duration": 177,
      "cover_url": "566d94bf-cc51-441b-9df2-ccee37481b70.jpg",
      "owner_handle": null,
      "owner_nickname": null,
      "is_original": false,
      "is_commerce_music": true,
      "usage_count": 3719051,
      "video_count": 1,
      "avg_views": 406
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12,
    "total_pages": 1,
    "has_next_page": false,
    "has_prev_page": false
  }
}

GET/v1/comet/:comet_id/sounds

Comet sounds

Returns the top sounds found within a Comet niche monitor, aggregated from the monitor's collected videos. Free — no credit charge.

Path parameters

Name
comet_id
Type
string
Required
*
Description
The Comet monitor UUID.

Query parameters

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/comet/:comet_id/sounds

curl -G https://api.virlo.ai/v1/comet/3d6012a2-9924-40f6-84db-8d354eb188a6/sounds \
  -H "Authorization: Bearer {token}" \
  -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
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 15,
    "total_pages": 1,
    "has_next_page": false,
    "has_prev_page": false
  }
}

Error responses

The sounds endpoints may return the following error codes:

Name
400 Bad Request
Description
Invalid parameters provided. Common causes: search query too short (min 2 characters), invalid limit/page values, invalid sort or platform values.
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 prepaid balance. Add funds at dev.virlo.ai/dashboard/billing.
Name
404 Not Found
Description
Sound not found. The specified sound_id does not exist in our database.
Name
429 Too Many Requests
Description
Rate limit exceeded. Wait before making additional requests.