---
title: "Search sounds by title"
method: GET
path: "/v1/sounds/search"
tags: ["Sounds"]
---

# Search sounds by title

`GET /v1/sounds/search`

## Request

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

Case-insensitive substring search across sound titles, ordered by usage_count (not fuzzy: a typo finds nothing). `q` needs at least one word of 3+ letters or digits; shorter queries are a 400 `validation_error`. Coverage grows daily as the dataset expands.

## Query parameters

- `q` string, required
- `platform` 'tiktok' | 'youtube' | 'instagram'
- `limit` number
- `page` number

## Response `200`

- SoundSearchResponseDto
  - `data` V1SoundDto[], 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.
  - `pagination` PaginationMetaDto, required
    - `page` number, required
    - `limit` number, required
    - `total` number, required
    - `total_pages` number, required
    - `has_next_page` boolean, required
    - `has_prev_page` boolean, required
  - `note` string, nullable: Advisory note when results are sparse

## 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)