# Tiktok Trending Music (`andrew_babo/tiktok-trending-music`) Actor

- **URL**: https://apify.com/andrew\_babo/tiktok-trending-music.md
- **Developed by:** [Andrew Babo](https://apify.com/andrew_babo) (community)
- **Stats:** 4 total users, 3 monthly users, 25.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TikTok Trending Music Scraper — Viral Sounds by Country + MP3 Download

Discover the songs and sounds going viral on **TikTok right now, per country** — ranked, enriched with the **official TikTok video-usage count**, and delivered with a **direct MP3 download link** for every sound. No login. No cookies. Built for content teams, affiliate marketers, and automated video pipelines.

### What you get

| Field | Description |
|---|---|
| `rank` | Position in the trending ranking for the chosen country |
| `title`, `artist` | Sound title and artist/creator |
| `videoCount` | Official number of TikTok videos using this sound |
| `videoCountDelta` | Growth since your previous run of this actor (same country) |
| `appearances`, `totalPlayCount` | How often the sound showed up in the trending-video scan and the combined views of those videos |
| `trendScore` | Composite score mixing frequency, views and growth |
| `duration` | Audio length in seconds |
| `isOriginalSound` | True for creator-made sounds (usually copyright-safe) |
| `audioUrl` | Direct MP3 link on TikTok's CDN (valid ~6 hours) |
| `audioDownloadUrl` | Permanent MP3 in the run's key-value store (when `downloadAudio` is on) |
| `soundUrl` | The sound's page on TikTok |

### Input

- **country** — two-letter code (`VN`, `US`, `JP`…). The scan runs through a residential IP in that country, so the ranking matches what local creators see. Default `VN`.
- **limit** — max sounds returned, ranked by trend score. Default 50.
- **scrollRounds** — scan depth; one round ≈ 15–25 trending videos. Default 8 (surfaces 80–150 unique sounds).
- **downloadAudio** — also store every MP3 in the run's key-value store and add `audioDownloadUrl`. Default off (you still get the direct `audioUrl`).
- **originalSoundsOnly** — keep only creator-made sounds. Default off.
- **failOnZeroResults** — fail the run hard when TikTok blocks the scan. Default off: the run writes an explanatory `noResults` row and finishes successfully, keeping schedules green.

### Cost & speed

Measured on real runs: **~60–80 seconds** per run at default depth, scanning 15–25 trending videos per country and enriching every returned sound with its official usage count and a verified MP3 link. Runs use residential proxies for accurate per-country results. Raise `scrollRounds` when you want a deeper scan.

### Tips

- Schedule the actor daily to build a trend history — `videoCountDelta` then shows which sounds are **breaking out** before they peak.
- Pipe `audioDownloadUrl` straight into a beat-analysis or video-editing actor to auto-cut footage on trending audio.
- Licensed commercial tracks may only offer a 30–60s preview — that is exactly the viral segment used in TikTok videos.

### For AI agents (MCP-ready)

This actor is available through the [Apify MCP Server](https://mcp.apify.com). Add it to Claude Desktop, Cursor, Windsurf or any MCP client, then use the skill below.

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/",
      "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
    }
  }
}
```

#### Agent skill: TikTok Trending Music Scout

```text
You are a music-trend scout for short-form video.

WHEN to call tiktok-trending-music:
- The user asks what songs/sounds are trending or viral on TikTok (in general or per country).
- The user needs trending audio for a video they are about to produce.
- The user wants to monitor a country's music trends over time (schedule runs; growth is in videoCountDelta).

PARAMETERS:
- country: 2-letter code, default "VN" unless the user names another market.
- limit: default 50; lower it (10-20) when the user only wants the very top.
- downloadAudio: set true ONLY when the user wants the MP3 files stored (e.g. to hand off to audio-beat-analyzer); otherwise false and share audioUrl links.
- Never invent values for unknown countries — pass the code the user gave.

OUTPUT INTERPRETATION:
- Rows are ranked; present rank, title, artist, videoCount, videoCountDelta and audioUrl.
- videoCountDelta > 0 with small videoCount = breakout sound, flag it as "rising".
- A row with status "noResults" is a VALID outcome: the scan was blocked that run. Say so plainly and suggest re-running — NEVER fabricate a trending list.
- isOriginalSound=true means creator-made audio, generally safe to reuse; licensed tracks may only have a 30-60s preview, which is the viral segment.
```

### How it works

The actor opens TikTok's Explore page through a residential IP in the target country with a real browser, collects the trending videos TikTok itself serves, aggregates the sounds they use, then enriches each top sound with its official usage count and a direct audio link. No account, no cookies, no stored credentials.

### Legal note

Audio previews are served from TikTok's public CDN exactly as the TikTok app fetches them. Respect copyright in your country: prefer `originalSoundsOnly` for commercial reuse, and always credit creators.

# Actor input Schema

## `country` (type: `string`):

Two-letter country code used to personalize what is trending, e.g. "VN", "US", "JP". The scrape runs through a residential IP in this country, so the ranking matches what local creators actually see. Use "US" for a global-ish English ranking.

## `limit` (type: `integer`):

Maximum number of trending sounds in the output, ranked by trend score. Each sound is enriched with its official TikTok video-usage count.

## `scrollRounds` (type: `integer`):

How many batches of trending videos to scan. One round is roughly 15-25 videos; more rounds give a more accurate ranking at slightly higher cost. 8 rounds usually surfaces 80-150 unique sounds.

## `downloadAudio` (type: `boolean`):

When enabled, the actor downloads each sound's MP3 preview into the run's key-value store and adds a permanent audioDownloadUrl to every item. Off by default: every item still includes audioUrl, a direct TikTok CDN link you can stream or download yourself (valid ~6 hours).

## `originalSoundsOnly` (type: `boolean`):

Restrict the output to original sounds created by TikTok users (not licensed commercial songs). Useful when you need copyright-safe audio for your own videos.

## `failOnZeroResults` (type: `boolean`):

Off by default: when TikTok blocks the scan, the run writes an explanatory status row and finishes successfully (keeps scheduled runs green). Turn on to make the run fail hard instead.

## Actor input object example

```json
{
  "country": "VN",
  "limit": 50,
  "scrollRounds": 8,
  "downloadAudio": false,
  "originalSoundsOnly": false,
  "failOnZeroResults": false
}
```

# Actor output Schema

## `RUN_SUMMARY` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "country": "VN"
};

// Run the Actor and wait for it to finish
const run = await client.actor("andrew_babo/tiktok-trending-music").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "country": "VN" }

# Run the Actor and wait for it to finish
run = client.actor("andrew_babo/tiktok-trending-music").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "country": "VN"
}' |
apify call andrew_babo/tiktok-trending-music --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,andrew_babo/tiktok-trending-music"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/YEU0PUweLIZy3PXFw/builds/FDeMXGJwWzU5SocYo/openapi.json