TikTok Get Song Details
Structured TikTok data: send music_ids. Cursor-paginated, 1 credit per successful call.
Overview
Section titled “Overview”Call GET /api/v2/tiktok-get-song-details/ with music_ids. The results are in data.items; send data.next_cursor back as cursor to get the next page. 6 optional parameters refine the call (see Parameters).
Request
Section titled “Request”curl -G "https://api.scrapier.io/api/v2/tiktok-get-song-details/" \ -H "X-API-Key: YOUR_API_KEY" \ --data-urlencode "music_ids=7439295283975702544" \ --max-time 210const params = new URLSearchParams({ music_ids: "7439295283975702544" });
const res = await fetch(`https://api.scrapier.io/api/v2/tiktok-get-song-details/?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, signal: AbortSignal.timeout(210_000),});const body = await res.json();if (!res.ok) throw new Error(body.error ?? body.detail ?? `HTTP ${res.status}`);
console.log(body.data.items);import requests
resp = requests.get( "https://api.scrapier.io/api/v2/tiktok-get-song-details/", headers={"X-API-Key": "YOUR_API_KEY"}, params={"music_ids": "7439295283975702544"}, timeout=210,)body = resp.json()if not resp.ok: raise RuntimeError(body.get("error") or body.get("detail"))
print(body["data"]["items"])curl -X POST "https://api.scrapier.io/api/v2/tiktok-get-song-details/" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"music_ids":"7439295283975702544"}' \ --max-time 210Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X-API-Key header | string | yes | — | Your API key from the dashboard. |
music_ids | string | yes | e.g. 7439295283975702544 | TikTok sound / song clip id (7439295283975702544 = SZA "luther"), a music page URL, a video URL (-> the sound it uses) or a vm./vt. short link. Required on the first call; ignored when cursor is supplied. One native TikTok item_list page (up to 30 videos) per call in mode videos; every row carries the sound's music_info block. |
cursor | string | no | — | Pagination cursor returned in the previous response's next_cursor. Pass it back unchanged to fetch the next page. When next_cursor is null, you have reached the last page. |
mode | string | no | videos | videos = one 30-video page per call (native offset cursor); song = single lookup of the sound's own record (one row, next_cursor null). videossong locked in cursor |
include_song_details | boolean | no | true | Attach music_info to every row (re-read from /api/music/detail/ on each page). Forced on in mode song. locked in cursor |
hydrate_song | boolean | no | true | Video-page hydration of music_info (full credit line, precise durations, matched-song id). locked in cursor |
include_artist_profile | boolean | no | true | Artist / owner profile pages -> artists[].is_verified + follower counts. locked in cursor |
region | string | no | — | ISO-2 market sent to the music API (also pins the proxy exit country; default US). locked in cursor |
Advanced
| Name | Type | Default | Description |
|---|---|---|---|
use_proxy | boolean | true | Route the request through Scrapier's residential proxy pool. Default: true. Leave as is unless support tells you otherwise. |
raw_data | boolean | false | When true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under raw_responses, in place of the formatted items. When false (default) you get the formatted output. Pagination (cursor / next_cursor) works the same in both modes. |
Response
Section titled “Response”{ "success": true, "data": { "music_ids": "7439295283975702544", "music_id": "7439295283975702544", "mode": "videos", "status": "ok", "page": 1, "page_size": 30, "offset": 0, "next_offset": 30, "has_more": true, "song": { "title": "luther", "author": "Kendrick Lamar & SZA", "url": "https://www.tiktok.com/music/luther-7439295283975702544", "is_original": false, "duration": 59, "user_count": 1400000, "artists": [ "sza" ], "cover_url": "https://p9-sg.tiktokcdn.com/aweme/720x720/tos-alisg-v-2774/ooCBAEtE4DqIfBLAjADiRIneQATZEYFgAh8tm8.jpeg", "play_url": "https://sf16-ies-music-sg.tiktokcdn.com/obj/tos-alisg-ve-2774/o8f9CfEFDdCEDUAq6gDqgOY4gQNfJHzxhF2ayE" }, "song_status": { "status": "ok", "status_code": 0, "status_msg": "ok" }, "request": { "mode": "videos", "region": null, "include_song_details": true, "hydrate_song": true, "include_artist_profile": true, "resolved_from": null }, "dropped": { "duplicates": 0 }, "warnings": [], "items": [ { "input_music": "7439295283975702544", "music_id": "7439295283975702544", "mode": "videos", "status": "ok", "position": 1, "video_id": "7488972085616823582", "url": "https://www.tiktok.com/@pettuan4/video/7488972085616823582", "description": "#fyp #pet #cat ", "content_type": "video", "created_at": "2025-04-03T06:37:47.000Z", "create_time_epoch": 1743662267, "author_username": "pettuan4", "author_id": "7352777357588055082", "author_display_name": "pettuan", "play_count": 50700000, "like_count": 8700000, "comment_count": 72800, "share_count": 3000000, "save_count": 470091, "repost_count": 0, "duration_seconds": 11, "hashtags": [ "fyp", "pet", "cat" ], "play_url": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/...?mime_type=video_mp4&...&tk=tt_chain_token", "cover_url": "https://p16-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/...~tplv-tiktokx-origin.image?...", "image_urls": [], "uses_requested_sound": true, "song": { "title": "luther", "author": "Kendrick Lamar & SZA", "...": "(same summary as above)" }, "request": { "mode": "videos", "region": null, "api_region": "BD", "include_song_details": true, "hydrate_song": true, "include_artist_profile": true, "max_items": 30 }, "pagination": { "cursor": 0, "next_offset": 30, "next_cursor": "eyJpZCI6eyJtc1Rva2VuIjoiLi4uIn0sImxrIjp7fSwibSI6Ijc0MzkyOTUyODM5NzU3MDI1NDQiLCJvZmYiOjMwLCJwIjoxLCJwb3MiOjMwLCJzIjpbIi4uLiJdLCJ1IjoiNzQzOTI5NTI4Mzk3NTcwMjU0NCJ9", "has_more": true, "server_cursor": 60, "page": 1, "source": "item_list" }, "post": { "id": "7488972085616823582", "url": "https://www.tiktok.com/@pettuan4/video/7488972085616823582", "content": { "text": "#fyp #pet #cat ", "media_urls": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/...", "thumbnail_url": "https://p16-common-sign.tiktokcdn.com/...", "duration_seconds": 11, "media_url_list": [ "https://v16-webapp-prime.tiktok.com/video/tos/alisg/...", "..." ], "download_url": "https://webapp-sg.tiktok.com/.../video/tos/alisg/...", "width": 576, "height": 1024, "ratio": "540p", "format": "mp4", "codec": "h264", "bitrate": 870697, "size_bytes": 1271109, "type": "video", "image_urls": [], "image_count": 0, "hashtags": [ "fyp", "pet", "cat" ], "mentions": [] }, "author": { "username": "pettuan4", "display_name": "pettuan", "avatar_url": "https://p16-common-sign.tiktokcdn.com/...", "verified": false, "id": "7352777357588055082", "sec_uid": "MS4wLjABAAAAMZNQGSYifu_8AR8kPLjNVHpGNAyKF5C3JsGorxxRazfn9JjlRY9cw1AGyKUWXVIV", "signature": "", "url": "https://www.tiktok.com/@pettuan4", "private_account": false }, "engagement": { "views": 50700000, "likes": 8700000, "comments": 72800, "shares": 3000000, "saves": 470091, "reposts": 0 }, "flags": { "nsfw": null, "spoiler": null, "pinned": false, "deleted": false, "private": false, "ad": false, "aigc": false, "original_item": false, "official_item": false, "duet_enabled": true, "stitch_enabled": true, "share_enabled": true, "comments_enabled": true, "is_reviewing": false, "is_prohibited": false }, "published_at": "2025-04-03T06:37:47.000Z", "ext": { "music_id": "7439295283975702544", "author_id": "7352777357588055082", "published_at_epoch": 1743662267, "music_title": "luther", "music_author": "Kendrick Lamar & SZA", "music_original": false, "uses_requested_sound": true, "author_followers": 10400, "author_following": 10, "author_video_count": 36, "author_total_likes": 8700000, "region": null, "text_language": "un", "category_type": 113, "diversification_id": 10019, "diversification_labels": [], "rank": 1, "page_offset": 0 } }, "computed": { "engagement_rate": 0.232205, "language": null, "content_category": "pets", "estimated_reach": 60840000, "engagement_rate_pct": 23.2205, "like_rate": 0.171598, "comment_rate": 0.001436, "share_rate": 0.059172, "save_rate": 0.009272, "total_interactions": 12242891, "age_days": 535.21, "views_per_day": 94728.98, "hashtag_count": 3, "mention_count": 0, "caption_length": 15, "is_short": true }, "music_info": { "album": "GNX", "author": "Kendrick Lamar & SZA", "title": "luther", "id_str": "7439295283975702544", "is_original": false, "is_pgc": true, "duration": 59, "user_count": 1400000, "artists": [ { "handle": "sza", "nick_name": "SZA", "is_verified": true, "uid": "7486547994222740523", "follower_count": 1241937, "url": "https://www.tiktok.com/@sza", "...": "(full artist block)" } ], "matched_song": { "id": "7440101671265486864", "title": "luther", "author": "Kendrick Lamar & SZA", "...": "(...)" }, "play_url": { "url_list": [ "https://sf16-ies-music-sg.tiktokcdn.com/obj/tos-alisg-ve-2774/o8f9..." ], "data_size": 956958, "mime_type": "audio/mp4", "...": "(...)" }, "tt_to_dsp_song_infos": [ { "platform": 3, "platform_name": "spotify", "song_id": "45J4avUb9Ni0bnETYaYFVJ", "url": "https://open.spotify.com/track/45J4avUb9Ni0bnETYaYFVJ", "meta_song_id": "7440101671265486864", "button_type": 2, "show_strategy": "1" } ], "url": "https://www.tiktok.com/music/luther-7439295283975702544", "is_copyrighted": true, "private": false, "sources": { "api_music_detail": true, "video_page_music": true, "artist_profiles": 1, "oembed": false, "embed_music": false, "audio_head": true, "page_video_id": "7488972085616823582" }, "...": "(every one of the 152 native music_info leaves is present; app-only leaves are null)" }, "song_status": { "status": "ok", "status_code": 0, "status_msg": "ok" }, "media_access": { "cookies": { "ttwid": "1%7C...", "tt_csrf_token": "...", "tt_chain_token": "..." }, "headers": { "referer": "https://www.tiktok.com/", "user-agent": "Mozilla/5.0 ... Chrome/131.0.0.0 Safari/537.36" }, "note": "post.content.media_urls / media_url_list / download_url need these cookies + Referer; thumbnail / cover / avatar URLs are open. URLs carry an expire= timestamp." }, "scraped_at": "2026-09-20T11:41:43.743Z" }, "... 29 more video rows in the same shape" ], "next_cursor": "eyJpZCI6eyJtc1Rva2VuIjoiLi4uIiwib2RpbklkIjoiMCIsInBhZ2VfY29va2llcyI6ey4uLn0sInR0d2lkIjoiLi4uIiwid2ViSWRMYXN0VGltZSI6MTc4OTkwNDUwNiwid2lkIjoiNzY4NzU4MTI4ODQyNTczNTcwMCJ9LCJsayI6e30sIm0iOiI3NDM5Mjk1MjgzOTc1NzAyNTQ0Iiwib2ZmIjozMCwicCI6MSwicG9zIjozMCwicmYiOm51bGwsInMiOlsiNzQ4ODk3MjA4NTYxNjgyMzU4MiIsIi4uLiJdLCJ1IjoiNzQzOTI5NTI4Mzk3NTcwMjU0NCJ9" }}Bad input. The exact message varies by endpoint.
{ "success": false, "error": "…"}Balance below the endpoint’s price.
{ "error": "Insufficient credits. Buy more to scrape more.", "balance": 1, "required": 2}Invalid or unknown API key.
{ "detail": "Authentication service unavailable or invalid API key."}Throttled — wait for Retry-After.
{ "detail": "Request was throttled. Expected available in N seconds."}Sample from the live catalog; arrays trimmed to 3 items. Results are in data.items.
Response fields
Section titled “Response fields”| Field | Type | Example | Description |
|---|---|---|---|
music_ids | string | 7439295283975702544 | — |
music_id | string | 7439295283975702544 | — |
mode | string | videos | — |
status | string | ok | — |
page | integer | 1 | — |
page_size | integer | 30 | — |
offset | integer | 0 | — |
next_offset | integer | 30 | — |
has_more | boolean | true | — |
song | object | {…} | — |
song_status | object | {…} | — |
request | object | {…} | — |
dropped | object | {…} | — |
warnings | array | [] | — |
items | array | [2 items] | The results. |
next_cursor | string | eyJpZCI6eyJtc1Rva2VuIjoiLi4uIiwib2RpbklkIjoiM… | Pass back as cursor for the next page. null on the last page. |
items[].input_music | string | 7439295283975702544 | — |
items[].music_id | string | 7439295283975702544 | — |
items[].mode | string | videos | — |
items[].status | string | ok | — |
items[].position | integer | 1 | — |
items[].video_id | string | 7488972085616823582 | — |
items[].url | string | https://www.tiktok.com/@pettuan4/video/748897… | — |
items[].description | string | #fyp #pet #cat | — |
items[].content_type | string | video | — |
items[].created_at | string | 2025-04-03T06:37:47.000Z | — |
items[].create_time_epoch | integer | 1743662267 | — |
items[].author_username | string | pettuan4 | — |
items[].author_id | string | 7352777357588055082 | — |
items[].author_display_name | string | pettuan | — |
items[].play_count | integer | 50700000 | — |
items[].like_count | integer | 8700000 | — |
items[].comment_count | integer | 72800 | — |
items[].share_count | integer | 3000000 | — |
items[].save_count | integer | 470091 | — |
items[].repost_count | integer | 0 | — |
items[].duration_seconds | integer | 11 | — |
items[].hashtags | array | [3 items] | — |
items[].play_url | string | https://v16-webapp-prime.tiktok.com/video/tos… | — |
items[].cover_url | string | https://p16-common-sign.tiktokcdn.com/tos-use… | — |
items[].image_urls | array | [] | — |
items[].uses_requested_sound | boolean | true | — |
items[].song | object | {…} | — |
items[].request | object | {…} | — |
items[].pagination | object | {…} | — |
items[].post | object | {…} | — |
items[].computed | object | {…} | — |
items[].music_info | object | {…} | — |
items[].song_status | object | {…} | — |
items[].media_access | object | {…} | — |
items[].scraped_at | string | 2026-09-20T11:41:43.743Z | — |
Pagination
Section titled “Pagination”Pass data.next_cursor back as cursor until it is null. Required inputs are ignored once a cursor is sent. Each page is one billed call. More in Pagination.
const url = "https://api.scrapier.io/api/v2/tiktok-get-song-details/";let params = { music_ids: "7439295283975702544" };const items = [];
for (let page = 0; page < 10; page++) { // each page is one billed call const res = await fetch(`${url}?${new URLSearchParams(params)}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, signal: AbortSignal.timeout(210_000), }); const body = await res.json(); if (!res.ok) throw new Error(body.error ?? body.detail ?? `HTTP ${res.status}`); const data = body.data; items.push(...(data.items ?? [])); if (!data.next_cursor) break; // null = last page params = { cursor: data.next_cursor };}import requests
URL = "https://api.scrapier.io/api/v2/tiktok-get-song-details/"HEADERS = {"X-API-Key": "YOUR_API_KEY"}params = {"music_ids": "7439295283975702544"}items = []
for _ in range(10): # each page is one billed call resp = requests.get(URL, headers=HEADERS, params=params, timeout=210) resp.raise_for_status() data = resp.json()["data"] items.extend(data.get("items") or []) if not data.get("next_cursor"): # None = last page break params = {"cursor": data["next_cursor"]}Errors
Section titled “Errors”Failed calls are free. Branch on the HTTP status and read the message from error (or detail). Full details in Errors.
| Status | Meaning | Retry? | Charged? |
|---|---|---|---|
400 | Bad or missing input. | No — fix the params | No |
401 / 403 | Missing, invalid or revoked API key. | No — fix the key | No |
402 | Out of credits (body has balance). | No — top up | No |
404 | Unknown endpoint slug. | No — check the slug | No |
429 / 503 | Busy or throttled. | Yes — after Retry-After | No |
5xx | Target site or upstream failure, or timeout. | Yes — with backoff | No |
- Locked into the cursor:
mode,include_song_details,hydrate_song,include_artist_profile,region. Set them on the first call; later pages reuse them. - This endpoint can take several minutes. Set your client timeout to at least 210 seconds.
Related
Section titled “Related”- TikTok Ad Library Leads — Structured TikTok data: every input is optional. Single lookup, 3 credits per successful call.
- TikTok Ad Library — Structured TikTok data: send
urls. Cursor-paginated, 1 credit per successful call. - TikTok Ads Top — Structured TikTok data: every input is optional. Cursor-paginated, 1 credit per successful call.
- TikTok Collection Videos — Structured TikTok data: send
urls. Cursor-paginated, 1 credit per successful call.