# Sounds

> Find trending and breakout sounds, search sounds by title, look up one sound (its videos, daily usage, and the real song behind it), and list every sound credited to an artist or creator across TikTok, YouTube, and Instagram.

Source: https://dev.virlo.ai/docs/sounds
Markdown: https://dev.virlo.ai/docs/sounds.md
Section: Explore data

## About the Virlo API (applies to every page)

- Base URL: `https://api.virlo.ai/v1`. Every request needs the header `Authorization: Bearer YOUR_API_KEY` (keys start with `virlo_tkn_`).
- Responses are JSON inside a `data` field, except the `/v1/webhooks` endpoints, which return the object or array directly. Field names are snake_case.
- Prices are in US dollars from a prepaid balance. 1 credit = $0.01. The `X-Cost` response header on each successful response is the exact charge. Errors are free.
- Slow jobs return an ID. Check its status every 15 seconds (or whatever `retry_after_seconds` says) until `finalized` is `true`.
- All docs pages: https://dev.virlo.ai/llms.txt. Every page in one file: https://dev.virlo.ai/llms-full.txt. MCP server for AI assistants: https://dev.virlo.ai/api/mcp/mcp.

---

See which songs and audio clips (sounds) are catching on across TikTok, YouTube, and Instagram, then dig into one.

**At a glance**

- **What it does:** Lists trending and breakout sounds, and looks up one sound or an artist's catalog.
- **You send:** A search word, a sound's `id`, an artist's name, or nothing for the trending lists.
- **You get back:** Sounds with usage numbers, or one sound's videos, daily history, and real song.
- **Cost:** $0.05 to $0.25 per request, even when nothing matches. Real-song matching adds $0.10 once per sound. Errors and Agent sounds are free.
- Sounds used most this week: [Trending sounds](https://dev.virlo.ai/docs/sounds#trending-sounds)
- Sounds suddenly taking off: [Breakout sounds](https://dev.virlo.ai/docs/sounds#breakout-sounds)
- A sound, found by its title: [Search sounds](https://dev.virlo.ai/docs/sounds#search-sounds)
- One sound's stats and real song: [Sound details](https://dev.virlo.ai/docs/sounds#sound-details)
- Top videos using a sound: [Sound videos](https://dev.virlo.ai/docs/sounds#sound-videos)
- How a sound grew day by day: [Usage history](https://dev.virlo.ai/docs/sounds#usage-history)
- Every sound credited to an artist: [Creator sounds](https://dev.virlo.ai/docs/sounds#creator-sounds)
- Sounds in your agent's videos: [Agent sounds](https://dev.virlo.ai/docs/sounds#agent-sounds)

These use Virlo's stored data. For fresh videos on one TikTok or Instagram sound, use [Sound lookup](https://dev.virlo.ai/docs/satellite/sounds): $0.50, or $1.00 with trend analysis.

---

## Sound basics

**Sound IDs.** `id` is Virlo's ID for a sound. Copy it from any list below or from a video's `sound` field. `external_id` is the platform's own ID and returns `404` where `id` is expected.

**Which count to trust.** `usage_count` is TikTok's all-time count of videos using the sound. Other counts only cover Virlo's data. To compare sounds, use `videos_in_window` (Trending) or `videos_7d` (Breakout). On Trending and Creator sounds, `video_count` and `avg_views` read too low, often `0`.

**Platforms.** TikTok has the fullest data. YouTube and Instagram sounds never have `usage_count` and are never marked commerce music. YouTube has no `duration`. Any field can be `null`, and `owner_handle` often is.

**Images.** `cover_url`, `thumbnail_url`, and `avatar_url` usually hold a file name. Put it after `https://auth.virlo.ai/storage/v1/object/public/` and the matching folder: `sound-covers/`, `thumbnails/`, or `avatars/`. Values starting with `https://` are already links. `""` or `null` means no image.

**Pages.** On Trending's 7-day and 30-day sorts, Breakout, and Agent sounds, `pagination.total` is not a real count. Keep paging while `has_next_page` is `true` ([Pagination](https://dev.virlo.ai/docs/pagination)).

**Errors.** Most bad options return a free `400`, and an unknown sound a free `404` ([Errors](https://dev.virlo.ai/docs/errors)). Some typos are ignored and still charged: a `commerce_only` other than `true`, a misspelled Creator sounds `platform`, and unknown options on Sound details.

**Fields on every sound**

Every sound has `id`, `external_id`, `title`, `platform`, `duration` (seconds), `cover_url`, `owner_handle`, `owner_nickname` (who the platform credits, not always the artist), `is_original`, `is_commerce_music` (`true` when TikTok clears it for ads and branded posts), and `usage_count`.

---

## Trending sounds

**Endpoint:** `GET https://api.virlo.ai/v1/sounds/trending`

The sounds used in the most new videos, over the last 7 days by default. Set `platform`, or YouTube sounds often fill the top.

Cost per request: $0.25

### Query parameters

- `platform` (string, optional): `tiktok`, `youtube`, or `instagram`. Default: all three.
- `sort` (string, optional): `videos_7d` (default) or `videos_30d`: most new videos in that window. `usage_count`: most used all time (TikTok first). `video_count`: avoid. It only reorders each page of the `usage_count` list.
- `commerce_only` (boolean, optional): Exactly `true` keeps only TikTok sounds cleared for ads. Other values, like `yes`, are ignored and you pay for the full list.
- `limit` (number, optional): 1 to 100. Default 20.
- `page` (number, optional): Default 1.

**Full field reference**

Each result has the [fields on every sound](https://dev.virlo.ai/docs/sounds#sound-basics), plus `video_count`, `avg_views`, and `videos_in_window` (the ranking number, on the 7-day and 30-day sorts only).

**cURL request:**

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

**JavaScript request:**

```js
const response = await fetch(
  'https://api.virlo.ai/v1/sounds/trending?platform=tiktok&sort=videos_7d&limit=20',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();
```

**Python request:**

```python
import requests

response = requests.get(
    'https://api.virlo.ai/v1/sounds/trending',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'platform': 'tiktok', 'sort': 'videos_7d', 'limit': 20}
)
data = response.json()
```

**Response 200:**

```json
{
  "data": [
    {
      "id": "53927570-5593-4bfe-b604-496d5aabd328",
      "external_id": "7668271352941742081",
      "title": "Vibin",
      "platform": "tiktok",
      "duration": 60,
      "cover_url": "13cb83d12e080a4b9e2609f79bebf1619b7700e6c2988b4a2c2ea8fe53819b61.jpg",
      "owner_handle": null,
      "owner_nickname": "Wxoda",
      "is_original": false,
      "is_commerce_music": false,
      "usage_count": 245774,
      "video_count": 0,
      "avg_views": 0,
      "videos_in_window": 51
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 21,
    "total_pages": 2,
    "has_next_page": true,
    "has_prev_page": false
  },
  "sort": "videos_7d"
}
```

**Response 400:**

```json
{
  "message": ["platform must be one of the following values: tiktok, youtube, instagram"],
  "error": "Bad Request",
  "statusCode": 400,
  "code": "validation_error"
}
```

---

## Breakout sounds

**Endpoint:** `GET https://api.virlo.ai/v1/sounds/breakout`

Sounds suddenly taking off from a quiet start, like 20 videos this week after about 1 a week before.

Results rank by `acceleration`: `(videos_7d + 1) / (prior_weekly + 1)`, where `prior_weekly` is the weekly average over days 8 to 35 ago. A sound needs at least `min_recent` videos this week, between `min_baseline` and 200 in the 4 weeks before, and an `acceleration` of 2+. Sounds above 200 show only in Trending.

Cost per request: $0.25

### Query parameters

- `platform` (string, optional): `tiktok`, `youtube`, or `instagram`. Default: all three.
- `commerce_only` (boolean, optional): Exactly `true` keeps only TikTok sounds cleared for ads, as in Trending.
- `min_recent` (number, optional): Minimum videos in the last 7 days. Default 3.
- `min_baseline` (number, optional): Minimum videos in days 8 to 35 ago. Default 3.
- `limit` (number, optional): 1 to 100. Default 20.
- `page` (number, optional): Default 1.

**Full field reference**

Each result has the [fields on every sound](https://dev.virlo.ai/docs/sounds#sound-basics), plus `videos_7d`, `videos_30d`, `videos_90d`, `prior_weekly`, and `acceleration` (ties go to more `videos_7d`). Two older scores always come back too: `burst_ratio` (`videos_7d / videos_90d`) and `breakout_score` (`videos_7d * burst_ratio`).

**cURL request:**

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

**JavaScript request:**

```js
const response = await fetch(
  'https://api.virlo.ai/v1/sounds/breakout?platform=tiktok&limit=20',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();
```

**Python request:**

```python
import requests

response = requests.get(
    'https://api.virlo.ai/v1/sounds/breakout',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'platform': 'tiktok', 'limit': 20}
)
data = response.json()
```

**Response 200:**

```json
{
  "data": [
    {
      "id": "f3c375de-0cac-4a4f-a23e-7fdfc13874d1",
      "external_id": "7678293159960676415",
      "title": "Courtly Elegance Boccherini",
      "platform": "tiktok",
      "duration": 45,
      "cover_url": "5a2e780f5bd991284fac706d04d0c0a3edc3787c057e21b8db823df33c9beb07.jpg",
      "owner_handle": null,
      "owner_nickname": "Lucien Marceau",
      "is_original": false,
      "is_commerce_music": false,
      "usage_count": 207622,
      "videos_7d": 10,
      "videos_30d": 13,
      "videos_90d": 13,
      "burst_ratio": 0.7692,
      "breakout_score": 7.6923,
      "prior_weekly": 0.75,
      "acceleration": 6.286
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 21,
    "total_pages": 2,
    "has_next_page": true,
    "has_prev_page": false
  }
}
```

---

## Search sounds

**Endpoint:** `GET https://api.virlo.ai/v1/sounds/search`

Find sounds whose title contains your text exactly as typed. Case doesn't matter, but spelling and word order do: `lofi beats` finds "chill stylish lofi beats", while `lofi beets` finds nothing but is still charged. When unsure, search one distinctive word.

Results sort by `usage_count`, so TikTok comes first.

Cost per request: $0.10

### Query parameters

- `q` (string, required): At least 2 characters. Commas and parentheses count as spaces.
- `platform` (string, optional): `tiktok`, `youtube`, or `instagram`. Default: all three.
- `limit` (number, optional): 1 to 100. Default 20.
- `page` (number, optional): Default 1.

**cURL request:**

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

**JavaScript request:**

```js
const response = await fetch(
  'https://api.virlo.ai/v1/sounds/search?q=lofi+beats&platform=tiktok&limit=20',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();
```

**Python request:**

```python
import requests

response = requests.get(
    'https://api.virlo.ai/v1/sounds/search',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'q': 'lofi beats', 'platform': 'tiktok', 'limit': 20}
)
data = response.json()
```

**Response 200:**

```json
{
  "data": [
    {
      "id": "81a0c517-fbb2-45ca-b2f5-d6d62d3e1a14",
      "external_id": "7358901665129662465",
      "title": "chill stylish lofi beats(1535963)",
      "platform": "tiktok",
      "duration": 190,
      "cover_url": "a6c30ceb5263d65db6be1b7161e24c7438ac7a97554f4ed436efe455bef948f5.jpg",
      "owner_handle": null,
      "owner_nickname": "Enokido",
      "is_original": false,
      "is_commerce_music": true,
      "usage_count": 50960
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 9,
    "total_pages": 1,
    "has_next_page": false,
    "has_prev_page": false
  }
}
```

**Response 200 No matches:**

```json
{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "total_pages": 0,
    "has_next_page": false,
    "has_prev_page": false
  },
  "note": "Sound search coverage grows daily as our dataset expands. Try broader terms or check back soon."
}
```

---

## Sound details

**Endpoint:** `GET https://api.virlo.ai/v1/sounds/:sound_id`

One sound's stats (video count, average views, top video), plus the real song behind it if you ask.

Cost per request: $0.05

### Find the real song

Add `resolve=true` to get the artist, the ISRC (a recording's standard code), and a Spotify ID when Spotify made the match. The answer is in `track_resolution` (always present).

- **Cost.** The first match adds $0.10 ($0.15 total), found or not, once per sound. Later reads cost $0.05.
- **Time.** A first match can take 15 seconds or more. If the match isn't done yet, `status` says `unresolved` or `pending` and you pay $0.05. Call again in about a minute.
- **Already matched.** Virlo matches some sounds in the background. If `status` is `resolved` or `not_found`, `resolve=true` won't look again, so leave it off.

### Path parameters

- `sound_id` (string, required): Virlo's sound `id`, not `external_id`.

### Query parameters

- `resolve` (boolean, optional): `true` or `1`. Other values are ignored.

**Full field reference**

The [fields on every sound](https://dev.virlo.ai/docs/sounds#sound-basics), plus:

- `total_videos` (integer, optional): Videos in Virlo's data using the sound. Stops counting at 1,000.
- `avg_views` (integer, optional): Their average views (over at most 1,000).
- `top_video_url` (string | null, optional): The most-viewed one.
- `track_resolution.status` (string, optional): `unresolved` (not matched yet), `pending` (matching now), `resolved`, or `not_found` (no confident match).
- `track_resolution.artist_name` (string | null, optional): The artist. Can differ from `owner_nickname`.
- `track_resolution.spotify_track_id` (string | null, optional): An ID, not a link: add it to `https://open.spotify.com/track/`. Only filled when Spotify (or sometimes audio fingerprinting) matched. `spotify_artist_id` works the same with `/artist/`.
- `track_resolution.apple_music_id` (string | null, optional): Not filled today: always `null`.
- `track_resolution.resolution_source` (string | null, optional): Who matched it. Catalogs first (`spotify`, `deezer`, `musicbrainz`), then `acrcloud` (audio fingerprint) and `llm_websearch` (AI web search).
- `track_resolution.confidence` (number | null, optional): 0 to 1. Also returned: `isrc`, `release_status` (`released`, `unreleased`, or `unknown`), `release_date`, `resolved_at`.

**cURL request:**

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

**Python request:**

```python
import requests

sound_id = '8f6e5c50-1451-4007-a120-92744e632dad'
response = requests.get(
    f'https://api.virlo.ai/v1/sounds/{sound_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'resolve': 'true'},
)
data = response.json()
```

**Response 200:**

```json
{
  "data": {
    "id": "8f6e5c50-1451-4007-a120-92744e632dad",
    "external_id": "7171140178143266818",
    "title": "I'll Never Let You Go",
    "platform": "tiktok",
    "duration": 62,
    "cover_url": "8bef57e2f1987f109f345a7b603ab2635277e7cb4f37a26ada16c11d07252572.jpg",
    "owner_handle": null,
    "owner_nickname": "BCD Studio",
    "is_original": false,
    "is_commerce_music": true,
    "usage_count": 86631999,
    "total_videos": 633,
    "avg_views": 1596202,
    "top_video_url": "https://www.tiktok.com/@cristineni34/video/7177832058478234885",
    "track_resolution": {
      "status": "resolved",
      "artist_name": "BCD Studio",
      "isrc": "SGB502290414",
      "spotify_track_id": "4fDHlmlEWbJnHa7dO5MZwW",
      "spotify_artist_id": "6ENUuaqy7QqbKD4M1X3siN",
      "apple_music_id": null,
      "release_status": "released",
      "resolution_source": "spotify",
      "release_date": null,
      "confidence": 1,
      "resolved_at": "2026-07-02T01:07:01.982+00:00"
    }
  }
}
```

**Response 404:**

```json
{
  "message": "Sound not found",
  "error": "Not Found",
  "statusCode": 404,
  "code": "not_found"
}
```

---

## Sound videos

**Endpoint:** `GET https://api.virlo.ai/v1/sounds/:sound_id/videos`

Videos in Virlo's data that use a sound, most-viewed first, to see how creators use it.

Cost per request: $0.25

### Path parameters

- `sound_id` (string, required): Virlo's sound `id`, not `external_id`.

### Query parameters

- `sort` (string, optional): `views_desc` (default): most views first. `publish_date_desc`: newest first.
- `platform` (string, optional): `tiktok`, `youtube`, or `instagram`. Rarely needed.
- `limit` (number, optional): 1 to 100. Default 20.
- `page` (number, optional): Default 1.

**Full field reference**

Each video has `id`, `url`, `description` (can be `""`), `platform`, `views`, `likes`, `shares`, `comments`, `bookmarks` (saves), `hashtags`, `is_duet`, `is_stitch`, and:

- `publish_date` (string, optional): No time zone marker. Read it as UTC.
- `thumbnail_url` (string | null, optional): A file name, often `""` (see [Images](https://dev.virlo.ai/docs/sounds#sound-basics)).
- `author` (object | null, optional): `username`, `verified`, `followers` (can be `null`), `avatar_url`.

**cURL request:**

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

**Python request:**

```python
import requests

sound_id = '8f6e5c50-1451-4007-a120-92744e632dad'
response = requests.get(
    f'https://api.virlo.ai/v1/sounds/{sound_id}/videos',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'sort': 'views_desc', 'limit': 20}
)
data = response.json()
```

**Response 200:**

```json
{
  "data": [
    {
      "id": "43721b48-f4f0-4ae4-8677-3f187aac28a4",
      "url": "https://www.tiktok.com/@cristineni34/video/7177832058478234885",
      "description": "",
      "platform": "tiktok",
      "views": 23135811,
      "likes": 600093,
      "shares": 228445,
      "comments": 15982,
      "bookmarks": 32971,
      "publish_date": "2022-12-16T19:34:22",
      "hashtags": [],
      "thumbnail_url": "",
      "is_duet": false,
      "is_stitch": false,
      "author": {
        "username": "cristineni34",
        "verified": false,
        "followers": 764158,
        "avatar_url": "8ed0b0d3-b8af-478a-b20f-d27e65bd1d0c.webp"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 633,
    "total_pages": 32,
    "has_next_page": true,
    "has_prev_page": false
  }
}
```

---

## Usage history

**Endpoint:** `GET https://api.virlo.ai/v1/sounds/:sound_id/usage-history`

A day-by-day record of one sound, from about one snapshot a day: TikTok's count, Virlo's count, and the change since the snapshot before.

**Always set `start_date`.** Snapshots come oldest first, and `limit` keeps the oldest. With no dates you get the first 90 ever recorded, which can be months old.

Cost per request: $0.05

No `pagination`.

### Path parameters

- `sound_id` (string, required): Virlo's sound `id`, not `external_id`.

### Query parameters

- `start_date` (string, optional): First day to include (YYYY-MM-DD).
- `end_date` (string, optional): Last day to include (YYYY-MM-DD).
- `limit` (number, optional): 1 to 365. Default 90.

**Full field reference**

Each snapshot has `usage_count` (TikTok only), `video_count_local`, `delta_usage_count`, `delta_video_count_local`, and `snapshot_at` (UTC). Deltas compare with the previous row in this response, so the first row's are always `null`. A stray `0` snapshot shows as a fake drop and jump back. Ignore it.

**cURL request:**

```bash
curl -G https://api.virlo.ai/v1/sounds/8f6e5c50-1451-4007-a120-92744e632dad/usage-history \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d start_date=2026-09-22 \
  -d end_date=2026-09-24
```

**Python request:**

```python
import requests

sound_id = '8f6e5c50-1451-4007-a120-92744e632dad'
response = requests.get(
    f'https://api.virlo.ai/v1/sounds/{sound_id}/usage-history',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'start_date': '2026-09-22', 'end_date': '2026-09-24'}
)
data = response.json()
```

**Response 200:**

```json
{
  "data": [
    {
      "usage_count": 83700000,
      "video_count_local": 628,
      "delta_usage_count": null,
      "delta_video_count_local": null,
      "snapshot_at": "2026-09-22T05:00:00.015+00:00"
    },
    {
      "usage_count": 84981718,
      "video_count_local": 628,
      "delta_usage_count": 1281718,
      "delta_video_count_local": 0,
      "snapshot_at": "2026-09-23T05:00:00.027+00:00"
    },
    {
      "usage_count": 86353566,
      "video_count_local": 630,
      "delta_usage_count": 1371848,
      "delta_video_count_local": 2,
      "snapshot_at": "2026-09-24T05:00:00.019+00:00"
    }
  ]
}
```

---

## Creator sounds

**Endpoint:** `GET https://api.virlo.ai/v1/sounds/by-creator/:platform/:handle`

Every sound credited to one artist or creator (their catalog), not the sounds they use in their videos. Your text is checked against each sound's credited handle, display name, and [matched artist](https://dev.virlo.ai/docs/sounds#sound-details).

**Start with the display name:** `tiktok/Kygo` finds 6 sounds, while the handle `tiktok/kygomusic` finds none. Every try is charged, even an empty one or a misspelled `platform`.

Cost per request: $0.25

### Path parameters

- `platform` (string, required): `tiktok`, `youtube`, or `instagram`.
- `handle` (string, required): Display name or handle, `@` optional. Spaces become `%20`: `Atomica%20Music`.

### Query parameters

- `sort` (string, optional): `usage_count` (default). `video_count`: avoid, as in Trending.
- `limit` (number, optional): 1 to 100. Default 20.
- `page` (number, optional): Default 1.

**Full field reference**

Each sound has the [fields on every sound](https://dev.virlo.ai/docs/sounds#sound-basics), plus `video_count` and `avg_views`. The response also has `aggregates`:

- `aggregates.total_sounds` (integer, optional): Sounds in the whole catalog.
- `aggregates.total_ugc_videos` (integer, optional): Sum of `video_count` **on this page only**, including the artist's own videos.
- `aggregates.total_usage_count` (integer, optional): Sum of `usage_count` **on this page only**.

**cURL request:**

```bash
curl -G https://api.virlo.ai/v1/sounds/by-creator/tiktok/Kygo \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d sort=usage_count \
  -d limit=20
```

**Python request:**

```python
import requests

response = requests.get(
    'https://api.virlo.ai/v1/sounds/by-creator/tiktok/Kygo',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'sort': 'usage_count', 'limit': 20}
)
data = response.json()
```

**Response 200:**

```json
{
  "data": [
    {
      "id": "ede0f487-8998-45b5-aef0-802a83c1e821",
      "external_id": "7094381072426747905",
      "title": "Freeze",
      "platform": "tiktok",
      "duration": 60,
      "cover_url": "fab1fb05c9863b5df89f8d81f22c109fa0e9d9b22c81bd36f0d5863d0a3318ef.jpg",
      "owner_handle": null,
      "owner_nickname": "Kygo",
      "is_original": false,
      "is_commerce_music": true,
      "usage_count": 8492,
      "video_count": 1,
      "avg_views": 433216
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 6,
    "total_pages": 1,
    "has_next_page": false,
    "has_prev_page": false
  },
  "aggregates": {
    "total_sounds": 6,
    "total_ugc_videos": 278,
    "total_usage_count": 28183
  }
}
```

---

## Agent sounds

**Endpoint:** `GET https://api.virlo.ai/v1/agents/:agent_id/sounds`

The sounds used most in the videos your [Content Research Agent](https://dev.virlo.ai/docs/agents) collected. **Free.** Here, `video_count` counts videos in the agent's results.

### Path parameters

- `agent_id` (string, required): Your agent's ID. A malformed ID returns `400`, and an agent you don't own returns `404`.

### Query parameters

- `sort` (string, optional): `video_count` (default), `usage_count`, or `rising` (most new videos since the previous run; old name `growth_7d`). Unknown values fall back to the default.
- `limit` (number, optional): 1 to 100. Default 20.
- `page` (number, optional): Default 1.

**Full field reference**

The [fields on every sound](https://dev.virlo.ai/docs/sounds#sound-basics), plus `video_count`, `avg_views`, and:

- `growth_video_count` (integer | null, optional): Change in `video_count` since the previous run, or `null` with no earlier run.
- `growth_views` (integer | null, optional): Change in their total views, also `null` with no earlier run.
- `lifecycle` (string, optional): Total views against the previous run: `rising` (up 25% or more), `fading` (down 25% or more), `steady`, or `new` (no earlier run).

**cURL request:**

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

**Python request:**

```python
import requests

agent_id = '2b1f9c3d-7c4e-4d8a-9f12-6e8b4a2c1d05'
response = requests.get(
    f'https://api.virlo.ai/v1/agents/{agent_id}/sounds',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'sort': 'rising', 'limit': 20}
)
data = response.json()
```

**Response 200:**

```json
{
  "data": [
    {
      "id": "9479ec9f-2150-40a9-8088-23b4b7979a76",
      "external_id": "7274023553422772278",
      "title": "Million Dolla Hip Hop",
      "platform": "tiktok",
      "duration": 188,
      "cover_url": "acc0a71eb81d1cbb7bc487047488722a2671dfc2f448d1c8b844ec6900ca3156.jpg",
      "owner_handle": null,
      "owner_nickname": "Brentin Davis",
      "is_original": false,
      "is_commerce_music": false,
      "usage_count": 86590,
      "video_count": 2,
      "avg_views": 53877,
      "growth_video_count": 1,
      "growth_views": 31792,
      "lifecycle": "rising"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 21,
    "total_pages": 2,
    "has_next_page": true,
    "has_prev_page": false
  }
}
```

**Response 404:**

```json
{
  "message": "Agent not found",
  "error": "Not Found",
  "statusCode": 404,
  "code": "not_found"
}
```

---

---

More in Explore data:

- [Trends](https://dev.virlo.ai/docs/trends.md)
- [Hooks](https://dev.virlo.ai/docs/hooks.md)
- [Hashtags](https://dev.virlo.ai/docs/hashtags.md)
- [Videos](https://dev.virlo.ai/docs/videos.md)