---
title: "Get sound details"
method: GET
path: "/v1/sounds/{sound_id}"
tags: ["Sounds"]
---

# Get sound details

`GET /v1/sounds/{sound_id}`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/sounds/{sound_id}`
- Auth: HTTP bearer

Full sound metadata with computed aggregate stats (total videos, average views, top video URL). Always returns a `track_resolution` object (sound → canonical recording: ISRC, DSP IDs, release status, and the recording artist) — `status: "unresolved"` until the sound has been resolved. Resolution runs a tiered fallback chain across multiple sources (so coverage survives Spotify API changes) and also reports `release_status` (`released` / `unreleased` / `unknown`): a verified ISRC ⇒ released, while a recording that exists but is absent from every catalogue ⇒ likely an unreleased "ID"/teaser/leak. `resolution_source` names the winning tier and `release_date` is included when known. Reads of an already-resolved sound are free. Pass `?resolve=true` to trigger an on-demand resolution which charges the `sound_artist_resolution` feature cost; re-reads of an already-resolved sound stay free even with `resolve=true`.

## Path parameters

- `sound_id` string, required

## Query parameters

- `resolve` boolean

## Response `200`

- SoundDetailResponseDto
  - `data` SoundDetailDataDto, required
    - `id` string, required: Virlo's internal sound ID (UUID). Use this for the /v1/sounds/:sound_id family (details, videos, usage-history, resolve). For the satellite sound lookup prefer `external_id`, though passing this UUID also works — it is auto-resolved to the sound's platform + external_id.
    - `external_id` string, nullable: Platform-native sound identifier (TikTok music/clip id, or Instagram audio id). This is the `music_id` accepted by the satellite sound lookup — call GET /v1/satellite/sounds/{platform}/{external_id} for TikTok or Instagram sounds. YouTube sounds are not supported (you'll get a 400). Null for sounds without a platform id.
    - `title` string, required
    - `platform` 'tiktok' | 'youtube' | 'instagram', required
    - `duration` number, nullable: Duration in seconds. Available on TikTok only.
    - `cover_url` string, nullable: Sound cover image URL. Available on TikTok and YouTube. Always an absolute URL (or null). Images Virlo stores are served from https://auth.virlo.ai/storage/v1/object/public/<bucket>/; platform CDN links are passed through. Some files are HEIC, which most non-Safari browsers cannot render, so convert before display if you need to.
    - `owner_handle` string, nullable: Sound owner handle. Partially available on TikTok (~12%).
    - `owner_nickname` string, nullable: Sound owner display name. Available on TikTok, YouTube, Instagram.
    - `is_original` boolean, nullable: Whether the sound is an original creation. TikTok only.
    - `is_commerce_music` boolean, nullable: Whether the sound is cleared for commercial use. TikTok only.
    - `usage_count` number, nullable: Platform-wide usage count. TikTok only.
    - `total_videos` number, required: All-time number of videos in our dataset using this sound. Updated within a few minutes of new videos arriving.
    - `avg_views` number, required: Average current views across all videos in our dataset using this sound (videos without a view count count as 0).
    - `top_video_url` string, nullable
    - `track_resolution` TrackResolutionDto, required
      - `status` 'unresolved' | 'pending' | 'resolved' | 'not_found', required: Resolution state. `unresolved` = never attempted; `pending` = queued for background resolution; `resolved` = matched to a recording artist; `not_found` = attempted but no confident match.
      - `artist_name` string, nullable
      - `isrc` string, nullable: International Standard Recording Code
      - `spotify_track_id` string, nullable
      - `spotify_artist_id` string, nullable
      - `apple_music_id` string, nullable
      - `release_status` 'released' | 'unreleased' | 'unknown', nullable: `released` = a verified ISRC was found in a registry/fingerprint source; `unreleased` = the recording was identified but is absent from every DSP/ISRC source (a TikTok "ID", teaser, leak, or pre-release); `unknown` = could not determine. Resolved via a tiered fallback chain so coverage survives Spotify API changes.
      - `resolution_source` 'spotify' | 'deezer' | 'musicbrainz' | 'acrcloud' | 'llm_websearch', nullable: Which resolver tier produced the winning answer.
      - `release_date` string, date, nullable: Recording release date when a source supplies one.
      - `confidence` number, nullable: 0..1 confidence of the match / release-status verdict.
      - `resolved_at` string, date-time, nullable

## Other responses

- `401`: Missing or invalid API key (`missing_api_key` / `invalid_api_key`)
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)