TikTok Popular Songs API
Creative Center popular/surging sounds — honoured{} names applied filters. Chart miss is 503 at 0 credits, not a For You sample.
GET request to /v1/tiktok/popular-songs that responds with clean JSON and costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh. Start with 100 free credits — no credit card.What is the TikTok Popular Songs API?
TikTok Creative Center sound chart (inspiration/popular/music). rankType=popular|surging, newOnBoard, commercialMusic (Commercial Music Library / ifCml — brand-safe), country, period (7/30/120), page. Each song: songId, clipId, title, artist, rankDiff, trend[] time series, growthRate, promoted. honoured{period,rankType,commercialMusic,newOnBoard} says which filters actually applied — period/rankType/commercialMusic/newOnBoard at the top level are only present when that path applied them. A chart blip is first rescued by the same parameters' last-good page from the past 24h — the chart is a 7/30/120-day aggregate, so a labelled snapshot (stale:true + cached:true, fetchedAt = scrape time, servedAt = now, 0 credits) is still the chart. A 503 CREATIVE_CENTER_UNAVAILABLE with retryable and retryAfterSeconds=60 at 0 credits fires only when there is no snapshot — we do not sell a For You feed sample as the chart (honoured all-false used to be a 2-credit 200 of 3–4 songs). After 3 fresh empty misses (replays do not count) persistent is true, the message stops saying retry shortly, and retryAfterSeconds becomes 300. Misses are remembered service-wide for 60s (300s once persistent) with cacheScope=service and replayed=true so a snapshotless retry is instant, not another 20–60s scrape. Hard 60s deadline: timeout is 502 UPSTREAM_UNAVAILABLE at 0 credits. page is echoed only on a native chart 200 together with hasMore / nextCursor (null — this is a page-number API). The extended actor is one shot: page is omitted, hasMore is true with truncatedReason=single_page_only only when the page filled. Cover art often has no x-expires / oe= (t= is a build token, not an expiry) — mediaUrlsExpireAt is then null, which means durable or unparseable, not a missing parser. Flat 2 credits on a chart 200 only. Pair with song-details / music-posts for a single sound's metadata and videos.
What you get
- rankType popular | surging · commercialMusic brand-safe filter when honoured
- rankDiff + trend[] on the Creative Center path
- Chart blip → 24h last-good page labelled stale at 0 credits
- 503 CREATIVE_CENTER_UNAVAILABLE (0 credits) only with no snapshot
- page only when it pages; hasMore / nextCursor always keyed
Try it
Fill in the parameters below and copy a ready-to-run request, or open the live Playground to run it against your account (no API key paste).
Parameters
curl "https://api.captapi.com/v1/tiktok/popular-songs" \
-H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."Edit the parameters and the code updates instantly. Switch languages and hit copy.
Example response
{
"success": true,
"data": {
"total": 2,
"items": [
{
"title": "Latest upload",
"url": "https://example.com/a",
"views": 90120,
"publishedAt": "2025-01-12"
},
{
"title": "Previous upload",
"url": "https://example.com/b",
"views": 75230,
"publishedAt": "2025-01-04"
}
]
}
}Billing metadata is returned in response headers: X-Captapi-Credits (credits charged), X-Captapi-Cache (hit or miss), and X-Captapi-Source. Failed requests (4xx/5xx) are never charged. See the full list of error codes in the error reference.
Response structure
A successful call returns success and a data object with the following fields:
Result
totalNumber of items returned.
Each item
Each item in items contains:
titleItem title.urlDirect URL to the content.viewsView count.publishedAtPublish date (ISO 8601).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| country | string | No | Two-letter ISO country. Default US. |
| period | integer | No | 7, 30, or 120 days (180→120). Default 7. |
| page | integer | No | Creative Center page (1–20). Echoed on a native chart 200 with hasMore. Omitted on the extended path — that list is one page. |
| rankType | string | No | popular | surging. Default popular. |
| newOnBoard | boolean | No | Only sounds newly on the Top 100. |
| commercialMusic | boolean | No | Only Commercial Music Library–cleared sounds. |
| limit | integer | No | Max items to return (default 20, max 20). Flat 2 credits per call. |
| cache | boolean | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. |
Authentication: send your key as Authorization: Bearer capt_live_.... A typical call costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh.
How it works
- 1. Sign up — get 100 free credits, no card required.
- 2. Create a key from your dashboard.
- 3. Send one request to
/v1/tiktok/popular-songsand parse the JSON response.
Use cases
Sound Trends
Track popular and surging TikTok sounds by market.
Brand-Safe Audio
Filter commercialMusic only when honoured.commercialMusic is true — otherwise the list is not brand-cleared.
Trend Analysis
Use trend[] time series and rankDiff for music marketing.
Frequently asked questions
What does the TikTok Popular Songs API do?+
The TikTok Popular Songs API lets you list items in bulk with metadata from a public TikTok sound or track using one GET request to /v1/tiktok/popular-songs. It returns clean JSON — no OAuth or infrastructure setup required.
How many credits does the TikTok Popular Songs API cost?+
Each successful call costs 2 credits. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.
Do I need a TikTok API key or OAuth?+
No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle proxies, rate limits, retries, and authentication for you.
Why did a 137s call cost 2 credits when my browser already hung?+
The origin used to finish past Cloudflare's ~125s read timeout, log a 200, and debit 2 credits after the connection was already dead — the same PH-1 hole popular-hashtags closed. The endpoint now has a 60s deadline: timeout is 502 UPSTREAM_UNAVAILABLE, 0 credits, with timings.totalMs. cache=true is still the fast path when a prior Creative Center 200 is in the 24h cache.
Why is this 503 instead of a song list?+
Only when there was nothing honest to serve. A chart blip is first rescued by the same parameters' last-good page from the past 24 hours, labelled stale:true + cached:true (fetchedAt = scrape time, servedAt = now) at 0 credits — the chart is a 7/30/120-day aggregate, so a day-old Top 100 is still the chart. We do not substitute a For You feed sample — that was 3–4 songs, none of the filters applied, billed at 2 credits. A 503 CREATIVE_CENTER_UNAVAILABLE (retryable, Retry-After 60s, 0 credits) means the chart missed and no snapshot existed for those parameters. requested{} is what you asked for.
Why was I charged 2 credits for three songs?+
You shouldn't be anymore. honoured all-false used to return a paid For You sample. That path is now 503 at 0 credits. A 200 is a chart (native or extended) and costs 2.
Is samplePlays / sampleVideoCount country-scoped?+
Those keys are gone. If a future row carries a play tally it is globalSamplePlays — TikTok-wide, not plays-in-VN — with globalSamplePlaysIsApproximate from the CP-F rule (v ≥ 10000 and v % 100 === 0). sampleVideoCount is omitted on the chart path.
How do I get page 2?+
On a native Creative Center 200, pass page=2 when hasMore is true (truncatedReason=chart-page). nextCursor is always null — this is a page-number API, not a cursor. The extended actor cannot page: page is omitted; a filled list is hasMore true, nextCursor null, truncatedReason=single_page_only (same rule as tiktok/trending-feed).
Why did three retries still say retry shortly?+
They shouldn't after the third fresh miss. retryable becomes false and the message stops saying retry shortly. Read retryable and the Retry-After header — consecutiveFailures / persistent stay in our metrics, not the payload.
Where are rankDiff and trend[]? The page promised them.+
On source=creative_center only (the ads.tiktok.com music chart). They are omitted — not null — when the chart does not answer. A miss is 503, not a placeholder list of uploads or original sounds.
Did commercialMusic / period / rankType actually apply?+
Read honoured{}, not the query string you sent. On a native Creative Center 200 every key is true and the matching top-level fields are echoed. On the extended chart actor only period and rankType are honoured — commercialMusic and newOnBoard are omitted from the envelope (not echoed as false-applied). A 503 carries requested{} only.
How long does coverUrl last?+
When the URL has x-expires, mediaUrlsExpireAt is that stamp (~48h). Many covers have only t= (a build token, not an expiry) and no oe= — then mediaUrlsExpireAt is null, which means durable or unparseable, not a missing parser. Persist songId; do not store coverUrl as a durable asset.
Is the TikTok Popular Songs API suitable for production use?+
Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.
More TikTok APIs
Ready to use the TikTok Popular Songs API?
Sign up, grab your key, and make your first call in 60 seconds.