---
title: "Get top sounds collected by a content research agent"
method: GET
path: "/v1/agents/{id}/sounds"
tags: ["Sounds"]
---

# Get top sounds collected by a content research agent

`GET /v1/agents/{id}/sounds`

## Request

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

Unified `/v1/agents` equivalent of the Orbit/Comet sounds reads — works for one-shot and recurring agents (the ID is interchangeable with a legacy orbit_id/comet_id). Returns sounds ranked by how many of the agent’s videos use them. Free — reads on already-paid-for data. Use `sort=rising` (or `growth_7d`) to rank by run-over-run momentum; rows carry `growth_video_count`, `growth_views`, and a `new`/`rising`/`steady`/`fading` `lifecycle` label (growth fields are null until the agent has two run snapshots). Pivot to `/v1/sounds/:sound_id/usage-history` for the full time-series.

## Path parameters

- `id` string, required

## Query parameters

- `limit` number
- `page` number
- `sort` 'video_count' | 'usage_count' | 'rising' | 'growth_7d'

## Response `200`

- NicheSoundsResponseDto
  - `data` NicheSoundItemDto[], 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.
    - `video_count` number, required: Videos using this sound within the search/niche
    - `avg_views` number, required
    - `growth_video_count` number, nullable: Phase 3 (Comet only): change in niche-local video_count since the previous run. null when there is no prior run snapshot yet (first observation). Populated on /v1/comet/:id/sounds.
    - `growth_views` number, nullable: Phase 3 (Comet only): change in niche-local total views since the previous run. null on first observation.
    - `lifecycle` 'new' | 'rising' | 'steady' | 'fading': Phase 3 (Comet only): run-over-run momentum label. `new` on first observation; otherwise `rising` (≥1.25×), `fading` (≤0.75×), or `steady`. Same thresholds as Virlo viral-insight trends.
  - `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

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