# TikTok Sound Videos Scraper (`automation-lab/tiktok-sound-videos-scraper`) Actor

Extract public TikTok sound metadata and representative videos from music URLs or IDs for trend research, creator discovery, and monitoring.

- **URL**: https://apify.com/automation-lab/tiktok-sound-videos-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Social media, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## TikTok Sound Videos Scraper

Extract public TikTok sound metadata and the representative videos TikTok exposes for each sound.

Provide one or many TikTok music URLs or numeric sound IDs.
The Actor returns a sound summary followed by typed video records with creators, captions, hashtags, play counts, covers, media URLs, dimensions, and playability signals.

It is designed for repeated sound research without login credentials, browser automation, or a paid third-party API.

### What does TikTok Sound Videos Scraper do?

For every requested public sound, the Actor:

1. normalizes the TikTok music URL or numeric ID;
2. opens TikTok's anonymous music embed surface;
3. extracts the server-rendered sound summary;
4. extracts the representative public video list;
5. saves one `sound` row and up to the requested number of `video` rows.

The output is intentionally bounded.
TikTok's anonymous embed usually exposes about 7–10 representative videos, not every video ever created with the sound.

### Who is it for?

#### Music and creator marketers

Compare sound adoption totals and inspect which representative creators or posts drive attention.

#### Trend researchers

Build a repeatable watchlist of sound IDs and track changes in reported video counts or visible representative posts.

#### Creator agencies

Find public creator handles, captions, hashtags, and play counts connected with campaign sounds.

#### Social-listening teams

Export compact sound snapshots into spreadsheets, BI tools, data warehouses, or scheduled monitoring jobs.

### Why use this Actor?

- **No login required:** it uses a public anonymous TikTok surface.
- **URL and ID inputs:** paste user-facing music links or store stable numeric IDs.
- **Batch support:** inspect multiple sounds in one run.
- **Typed records:** distinguish sound summaries from video rows with `recordType`.
- **Cost control:** set `maxVideosPerSound` from 1 to 20.
- **Honest scope:** the Actor does not claim exhaustive pagination.
- **Integration ready:** every run writes to the default Apify dataset.

### What TikTok sound data can I extract?

| Field | Record | Meaning |
| --- | --- | --- |
| `recordType` | Both | `sound` or `video` |
| `soundId` | Both | Stable numeric TikTok sound identifier |
| `sourceUrl` | Both | Anonymous music embed URL used for extraction |
| `artist` | Sound | Artist or attribution exposed by TikTok |
| `coverUrl` | Both | Sound artwork or video cover URL |
| `videoCount` | Sound | Total videos TikTok reports for the sound |
| `representativeVideosReturned` | Sound | Number of video rows emitted in this run |
| `videoId` | Video | TikTok video ID |
| `videoUrl` | Video | Canonical public video page URL |
| `description` | Video | Public video caption |
| `hashtags` | Video | Hashtags parsed from the caption |
| `authorHandle` | Video | Public creator handle |
| `playCount` | Video | Plays reported at scrape time |
| `mediaUrl` | Video | Temporary playback CDN URL, when available |
| `width`, `height`, `ratio` | Video | Media dimensions and resolution label |
| `isPrivate` | Video | TikTok privacy signal |
| `isPlayable` | Video | Public row includes a playback address |
| `scrapedAt` | Both | UTC extraction timestamp |

Nullable fields can be `null` when TikTok does not expose them.
CDN URLs can expire; use `videoUrl` as the durable reference.

### How to get started

1. Open the Actor in Apify Console.
2. Add one or more public TikTok music URLs under **TikTok sound URLs**.
3. Alternatively, add numeric values under **TikTok sound IDs**.
4. Choose the maximum representative videos per sound.
5. Click **Start**.
6. Open the **Dataset** tab to review or export results.

A small first run with one sound and five videos is recommended.

### Input

#### `startUrls`

An optional array of public TikTok sound/music URLs.
Supported shapes include:

```text
https://www.tiktok.com/music/original-sound-7149523537730997035
https://www.tiktok.com/embed/music/7149523537730997035
```

Only `tiktok.com` URLs are accepted.
A malformed URL or a URL without a numeric sound ID fails input validation.

#### `soundIds`

An optional array of 10–30 digit TikTok sound IDs.
IDs are useful for stable scheduled monitoring.
You can combine `soundIds` and `startUrls`; duplicates are fetched once.

#### `maxVideosPerSound`

An integer from 1 to 20.
The default is 10.
This limits rows from TikTok's representative list; it does not request exhaustive pagination.

At least one URL or ID is required.

### Input example

```json
{
  "soundIds": [
    "6889520563052645121",
    "7149523537730997035"
  ],
  "maxVideosPerSound": 3
}
```

This batch produces up to two sound rows and six representative video rows.

### Output example

A current public sound produces a summary such as:

```json
{
  "recordType": "sound",
  "soundId": "7149523537730997035",
  "sourceUrl": "https://www.tiktok.com/embed/music/7149523537730997035",
  "artist": "HBO Max",
  "coverUrl": "https://p16-sign.tiktokcdn.com/...",
  "videoCount": 63600,
  "representativeVideosReturned": 3,
  "scrapedAt": "2025-01-15T12:00:00.000Z"
}
```

A representative video row looks like:

```json
{
  "recordType": "video",
  "soundId": "7149523537730997035",
  "videoId": "7149523510589754670",
  "videoUrl": "https://www.tiktok.com/@hbomax/video/7149523510589754670",
  "description": "I'll take one of each. #houseofthedragon",
  "hashtags": ["houseofthedragon"],
  "authorHandle": "hbomax",
  "playCount": 35700000,
  "width": 576,
  "height": 1024,
  "ratio": "540p",
  "isPrivate": false,
  "isPlayable": true
}
```

Counts and representative videos change over time.

### How much does it cost to extract TikTok sound videos?

The Actor charges per dataset item.
A sound summary and each representative video are each one `item` event.
A one-time **$0.00005 run-start event** covers initialized-run tracking.

Current FREE-tier price: **$0.0001679 per item**.
Higher Apify usage tiers receive lower item prices down to **$0.00004088 per item** on DIAMOND.

Examples at the FREE-tier item price:

| Workflow | Maximum rows | Estimated Actor charge |
| --- | ---: | ---: |
| 1 sound + 5 videos | 6 | about $0.00106 |
| 10 sounds + 10 videos each | 110 | about $0.0185 |
| 100 sounds + 3 videos each | 400 | about $0.0672 |

Actual rows can be lower when TikTok exposes fewer representative videos.
Apify platform usage and proxy charges, if applicable to your plan, are separate from Actor item charges.

### Monitoring and automation workflows

#### Weekly sound adoption tracking

Schedule the Actor with stable sound IDs.
Compare `videoCount` and representative `playCount` values between runs in your warehouse.

#### Creator discovery

Filter video rows by `playCount`, group by `authorHandle`, and open `videoUrl` for manual campaign review.
Representative results are leads, not an exhaustive creator list.

#### Hashtag enrichment

Flatten `hashtags` from video rows and combine them with sound-level totals for content planning.

#### Alerts

Use an Apify webhook to trigger your automation when a scheduled run succeeds.
Send unusually large changes to Slack, email, or a database workflow.

### Export and integrations

The default dataset supports JSON, CSV, Excel, XML, RSS, and JSONL exports.

Common destinations include:

- Google Sheets via Make or Zapier;
- BigQuery, Snowflake, or PostgreSQL;
- Python notebooks and pandas;
- dashboards and internal trend reports;
- Slack or email alerting workflows.

Use `recordType` to split summary and video records downstream.

### API usage with cURL

Start a run and wait for completion:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~tiktok-sound-videos-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"soundIds":["7149523537730997035"],"maxVideosPerSound":5}'
```

Keep your Apify token in an environment variable.
Do not commit it to source control.

### API usage with JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/tiktok-sound-videos-scraper').call({
  soundIds: ['7149523537730997035'],
  maxVideosPerSound: 5,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### API usage with Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/tiktok-sound-videos-scraper").call(
    run_input={
        "soundIds": ["7149523537730997035"],
        "maxVideosPerSound": 5,
    }
)
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with Apify MCP

#### Claude Code setup

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/tiktok-sound-videos-scraper"
```

#### Claude Desktop setup

Use this JSON configuration in Claude Desktop:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/tiktok-sound-videos-scraper"
    }
  }
}
```

#### Cursor setup

Add the same HTTP MCP URL in **Cursor Settings → MCP → Add server** and name it `apify`.

#### VS Code setup

Add the same HTTP MCP URL as an MCP server in your VS Code workspace or user MCP configuration.

Example prompts:

- “Run TikTok Sound Videos Scraper for these three sound IDs and rank representative videos by play count.”
- “Compare reported adoption for these two TikTok music URLs.”
- “Extract creator handles and hashtags from this public TikTok sound.”

### Reliability and retry behavior

The Actor retries temporary network failures, HTTP 429 responses, and TikTok server errors with bounded exponential backoff.
It does not blindly retry invalid input, missing public data, or changed markup.

When a batch contains a failed sound, the Actor logs that sound and continues with the rest.
The run fails if no useful record can be extracted from any requested sound.
This prevents false successful runs with an empty dataset.

No automatic residential-proxy fallback is enabled in this release.

### Limitations

- TikTok chooses the representative video list; it is not exhaustive or guaranteed to be sorted.
- The anonymous embed normally exposes about 7–10 videos even if the total `videoCount` is much larger.
- TikTok can change the embed markup or restrict public sounds by region.
- Deleted, private, unavailable, or invalid sound IDs may fail.
- `playCount` and `videoCount` are point-in-time values.
- Playback and cover CDN URLs may expire.
- The Actor does not download media files.
- The Actor does not bypass login, privacy settings, or access controls.

### Troubleshooting

#### “Could not find a TikTok sound ID”

Use a public `/music/...-{numericId}` or `/embed/music/{numericId}` URL.
Profile, hashtag, search, and video URLs are not sound inputs.

#### “TikTok did not expose public sound data”

Confirm the sound opens publicly in your region and has not been removed.
Try the numeric ID from the music URL.

#### The result contains fewer videos than requested

`maxVideosPerSound` is a ceiling.
TikTok may expose fewer representative videos on its anonymous embed.

#### The media URL stopped working

Use `videoUrl` to revisit the public post.
Signed CDN playback addresses are temporary by design.

### Responsible use and legality

Use this Actor only for public data you are authorized to access and process.
Follow TikTok's terms, applicable laws, and your organization's privacy and retention policies.

Do not use results for harassment, discrimination, invasive profiling, or attempts to identify private individuals.
Minimize stored personal data and honor valid deletion or access requests when required.

This Actor accesses public anonymous pages and does not circumvent account controls.
You are responsible for the purpose and downstream use of collected data.

### Related Automation Lab Actors

- [TikTok Profile Scraper](https://apify.com/automation-lab/tiktok-profile-scraper) — enrich a known creator handle with public profile data.
- [TikTok Hashtag Scraper](https://apify.com/automation-lab/tiktok-hashtag-scraper) — investigate hashtag-centered public videos instead of sound-centered samples.
- [TikTok Video Scraper](https://apify.com/automation-lab/tiktok-video-scraper) — extract details for known TikTok video URLs.

Choose this Actor when the starting point is a sound or music ID.

### FAQ

#### Does it return every video using a sound?

No.
It returns the representative videos exposed by TikTok's anonymous embed plus TikTok's reported total video count.

#### Does it require TikTok credentials?

No login, session cookie, or TikTok API key is required.

#### Can I pass duplicate URLs and IDs?

Yes.
The Actor normalizes and deduplicates sound IDs within a run.

#### Can I schedule recurring checks?

Yes.
Store numeric sound IDs in a scheduled task and compare datasets between runs.

#### Does it download video or audio files?

No.
It returns metadata, public page URLs, covers, and temporary media URLs when TikTok exposes them.

#### What happens if one sound fails in a batch?

The Actor logs that sound and continues.
The run succeeds if at least one sound produced useful records; it fails if all sounds fail.

#### Why are sound and video rows in one dataset?

A shared default dataset makes API and export integrations straightforward.
Use `recordType` to separate them downstream while retaining the sound ID relationship.

# Actor input Schema

## `startUrls` (type: `array`):

Public TikTok music/sound URLs, including standard /music/...-{id} and /embed/music/{id} URLs.

## `soundIds` (type: `array`):

Optional array of numeric TikTok sound IDs. You can combine these with sound URLs.

## `maxVideosPerSound` (type: `integer`):

Limit videos saved from TikTok's anonymous representative embed list. This does not paginate the full sound catalog.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.tiktok.com/music/original-sound-7149523537730997035"
    }
  ],
  "soundIds": [],
  "maxVideosPerSound": 10
}
```

# Actor output Schema

## `dataset` (type: `string`):

Sound summaries and representative videos in the default dataset.

# 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 = {
    "startUrls": [
        {
            "url": "https://www.tiktok.com/music/original-sound-7149523537730997035"
        }
    ],
    "maxVideosPerSound": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/tiktok-sound-videos-scraper").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 = {
    "startUrls": [{ "url": "https://www.tiktok.com/music/original-sound-7149523537730997035" }],
    "maxVideosPerSound": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/tiktok-sound-videos-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.tiktok.com/music/original-sound-7149523537730997035"
    }
  ],
  "maxVideosPerSound": 10
}' |
apify call automation-lab/tiktok-sound-videos-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/tiktok-sound-videos-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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