{"openapi":"3.1.0","info":{"title":"Tokchart API","version":"0.1.1"},"servers":[{"url":"https:\/\/tokchart.com\/api\/v1"}],"tags":[{"name":"Discovery API"},{"name":"Campaign Management"},{"name":"Trending Songs"},{"name":"TikTok Audio Trending"},{"name":"Tracked Artists"},{"name":"Tracked Songs"},{"name":"TikTok Creators"}],"security":[{"http":[]}],"paths":{"\/campaigns\/tiktok":{"post":{"operationId":"customerCampaign.createTiktokCampaign","description":"Requires the **Create, update and read campaigns** permission.","summary":"Create a new TikTok campaign","tags":["Campaign Management"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The campaign name.","examples":["Summer Music Campaign 2024"],"maxLength":255},"sound_id":{"type":["string","null"],"description":"The TikTok sound ID or tiktok.com\/music link to associate with the campaign.","examples":["7123456789012345678"]},"start_date":{"type":["string","null"],"format":"date","description":"The campaign start date.","examples":["2024-01-01"]},"end_date":{"type":["string","null"],"format":"date","description":"The campaign end date.","examples":["2024-12-31"]},"starting_sound_videos_count":{"type":["integer","null"],"description":"The initial count of videos using the sound.","examples":[1000],"minimum":0},"links":{"type":"array","description":"List of TikTok video URLs to add to the campaign.","examples":[["https:\/\/www.tiktok.com\/@user\/video\/7123456789012345678"]],"items":{"type":"string","description":"A TikTok video URL.","examples":["https:\/\/www.tiktok.com\/@user\/video\/7123456789012345678"]}}},"required":["name"]}}}},"responses":{"201":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string"},"name":{"type":["string","null"]},"sound_id":{"type":["string","null"]},"start":{"type":["string","null"]},"end":{"type":["string","null"]},"starting_sound_videos_count":{"type":["integer","null"]},"links_added":{"type":"integer","minimum":0},"message":{"type":"string","const":"Campaign created successfully"}},"required":["uuid","name","sound_id","start","end","starting_sound_videos_count","links_added","message"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/campaigns\/instagram":{"post":{"operationId":"customerCampaign.createInstagramCampaign","description":"Requires the **Create, update and read campaigns** permission.","summary":"Create a new Instagram campaign","tags":["Campaign Management"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The campaign name.","examples":["Instagram Reels Campaign 2024"],"maxLength":255},"ig_sound_id":{"type":["string","null"],"description":"The Instagram sound ID or instagram.com\/reels\/audio link to associate with the campaign.","examples":["1234567890"]},"start_date":{"type":["string","null"],"format":"date","description":"The campaign start date.","examples":["2024-01-01"]},"end_date":{"type":["string","null"],"format":"date","description":"The campaign end date.","examples":["2024-12-31"]},"starting_sound_videos_count":{"type":["integer","null"],"description":"The initial count of reels using the sound.","examples":[500],"minimum":0},"links":{"type":"array","description":"List of Instagram Reel URLs to add to the campaign.","examples":[["https:\/\/www.instagram.com\/reel\/Cx1y2z3A4B5\/"]],"items":{"type":"string","description":"An Instagram Reel URL.","examples":["https:\/\/www.instagram.com\/reel\/Cx1y2z3A4B5\/"]}}},"required":["name"]}}}},"responses":{"201":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"uuid":{"type":["string","null"]},"name":{"type":["string","null"]},"ig_sound_id":{"type":["string","null"]},"start":{"type":["string","null"]},"end":{"type":["string","null"]},"starting_sound_videos_count":{"type":["integer","null"]},"links_added":{"type":"integer","minimum":0},"message":{"type":"string","const":"Campaign created successfully"}},"required":["uuid","name","ig_sound_id","start","end","starting_sound_videos_count","links_added","message"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/campaigns\/tiktok\/{campaign}":{"post":{"operationId":"customerCampaign.addTiktokUrls","description":"Send the campaign's full list of links each time: links not in the list are\nremoved from the campaign, and every link in it is imported again.\n\nRequires the **Create, update and read campaigns** permission.","summary":"Set a TikTok campaign's video URLs","tags":["Campaign Management"],"parameters":[{"name":"campaign","in":"path","required":true,"description":"The campaign UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"links":{"type":"array","description":"List of TikTok video URLs to add.","examples":[["https:\/\/www.tiktok.com\/@user\/video\/7123456789012345678","https:\/\/www.tiktok.com\/@anotheruser\/video\/7987654321098765432"]],"items":{"type":"string","description":"A TikTok video URL.","examples":["https:\/\/www.tiktok.com\/@user\/video\/7123456789012345678"]}}},"required":["links"]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]},{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"No new links to import"}},"required":["success","message"]},{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":["string","null"]}},"required":["success","message"]},{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"Campaign not found"}},"required":["success","message"]}]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"403":{"description":"An error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview.","examples":[""]}},"required":["message"]}}}},"404":{"$ref":"#\/components\/responses\/ModelNotFoundException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"get":{"operationId":"customerCampaign.showTiktok","description":"The campaign's report, as on its page and in its CSV: totals across its posts, the change over the last\nday, videos using the campaign sound, and every post with its creator and latest stats.\n\n`totals` sum each post's latest stats; `engagement_rate` is the average of the posts' rates, in percent.\n`last_day` is the change since the last stats update at least 20 hours older (empty until there are two).\n`daily` has the campaign's totals at each day's last stats update, oldest first.\n\n`sound_videos.daily` has the new videos with the campaign sound each day, for the last 45 days. `sound_countries`\nhas the top five countries where the sound is used, by share of its videos, and is empty when we have no\nfigures yet.\n\n`campaign.sound.tiktok_url` (also `url`) is the sound's page on TikTok; `campaign.sound.cover_url` and each post's\n`cover_url` are images, null when there is none. Images and links are for display and attribution only (see the\nAPI terms).\n\nEach post's `status` is `added`, `checking` (Tokchart is still fetching it) or `failed` (the link could not\nbe read). Only added posts have a creator and stats; `stats` is null until the post's first stats update.\n`unavailable` is true when the post has since been removed from TikTok.\n\nAvailable with any API token on a Business or higher plan, or with the **Create, update and read campaigns** permission. Returns 404 for a campaign that is not yours.","summary":"Get a TikTok campaign report","tags":["Campaign Management"],"parameters":[{"name":"campaign","in":"path","required":true,"description":"The campaign `uuid`.","schema":{"type":"string"},"example":"9b2f6c1e-3d4a-4f8b-a1c2-7e5d9f0b3a68"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"campaign":{"sound":{"id":"7123456789012345678","title":"Example song","artist":"Example artist","url":"https:\/\/www.tiktok.com\/music\/example-song-7123456789012345678","tiktok_url":"https:\/\/www.tiktok.com\/music\/example-song-7123456789012345678","cover_url":"https:\/\/assets.tokchart.com\/images\/sounds_data\/cover\/example.webp"},"uuid":"9b2f6c1e-3d4a-4f8b-a1c2-7e5d9f0b3a68","name":"Summer Music Campaign 2026","platform":"tiktok","start_date":"2026-10-01","end_date":"2026-10-31","archived":false,"created_at":"2026-09-28T10:15:00+00:00","updated_at":"2026-10-20T08:02:11+00:00","status":"live","updating":false,"stats_updated_at":"2026-10-20T08:00:00+00:00","share_url":"https:\/\/tokchart.com\/campaigns\/9b2f6c1e-3d4a-4f8b-a1c2-7e5d9f0b3a68"},"totals":{"posts":41,"creators":38,"views":1834200,"likes":210450,"comments":3120,"shares":8410,"saves":15230,"engagement_rate":11.87},"last_day":{"views":52300,"likes":4100,"comments":64,"shares":210,"saves":380},"sound_videos":{"start":1200,"now":3480,"change_percent":190,"daily":[{"date":"2026-10-19","new_videos":96},{"date":"2026-10-20","new_videos":118}]},"sound_countries":[{"code":"US","name":"United States","share_percent":41.25},{"code":"BR","name":"Brazil","share_percent":18.4}],"links":{"submitted":42,"added":41,"checking":0,"failed":1},"posts":[{"url":"https:\/\/www.tiktok.com\/@creator\/video\/7123456789012345678","status":"added","unavailable":false,"type":null,"posted_at":"2026-10-03T17:42:10+00:00","cover_url":"https:\/\/assets.tokchart.com\/video_thumbnails\/7123456789012345678","creator":{"handle":"creator","profile_url":"https:\/\/www.tiktok.com\/@creator","country":"US","followers":254000},"stats":{"views":412000,"likes":51200,"comments":610,"shares":1840,"saves":3920,"engagement_rate":14.05,"views_to_followers":162.2}},{"url":"https:\/\/www.tiktok.com\/@another\/video\/7987654321098765432","status":"failed","unavailable":false,"type":null,"posted_at":null,"cover_url":null,"creator":null,"stats":null}],"daily":[{"date":"2026-10-19","views":1781900,"likes":206350,"comments":3056,"shares":8200,"saves":14850},{"date":"2026-10-20","views":1834200,"likes":210450,"comments":3120,"shares":8410,"saves":15230}]}],"properties":{"campaign":{"type":"string"},"totals":{"type":"object","properties":{"posts":{"type":"integer","minimum":0},"creators":{"type":"integer","minimum":0},"views":{"type":"integer"},"likes":{"type":["integer","null"]},"comments":{"type":["integer","null"]},"shares":{"type":["integer","null"]},"saves":{"type":["integer","null"]},"engagement_rate":{"type":["number","null"]}},"required":["posts","creators","views","likes","comments","shares","saves","engagement_rate"]},"last_day":{"type":"string"},"sound_videos":{"type":["object","null"],"properties":{"start":{"type":"string"},"now":{"type":"string"},"change_percent":{"type":["number","null"]},"daily":{"type":"array","items":{}}},"required":["start","now","change_percent","daily"]},"sound_countries":{"type":"array","items":{}},"links":{"type":"object","properties":{"submitted":{"type":"integer","minimum":0},"added":{"type":"integer","minimum":0},"checking":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0}},"required":["submitted","added","checking","failed"]},"posts":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"status":{"type":"string"},"unavailable":{"type":"boolean"},"type":{"type":["string","null"]},"posted_at":{"type":"null"},"cover_url":{"type":["string","null"]},"creator":{"type":["object","null"],"properties":{"handle":{"type":"string"},"profile_url":{"type":"string"},"country":{"type":["string","null"]},"followers":{"type":["integer","null"]}},"required":["handle","profile_url","country","followers"]},"stats":{"type":["object","null"],"properties":{"views":{"type":["integer","null"]},"likes":{"type":["integer","null"]},"comments":{"type":["integer","null"]},"shares":{"type":["integer","null"]},"saves":{"type":["integer","null"]},"engagement_rate":{"type":["number","null"]},"views_to_followers":{"type":["number","null"]}},"required":["views","likes","comments","shares","saves","engagement_rate","views_to_followers"]}},"required":["url","status","unavailable","type","posted_at","cover_url","creator","stats"]}},"daily":{"type":"array","items":{"type":"string"}}},"required":["campaign","totals","last_day","sound_videos","sound_countries","links","posts","daily"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"campaign_not_found","message":"You have no campaign with this UUID."}],"properties":{"error":{"type":"string","const":"campaign_not_found"},"message":{"type":"string","const":"You have no campaign with this UUID."}},"required":["error","message"]}}}},"403":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"campaigns_not_included","message":"Reading campaigns needs a Business or higher plan, or a token with the campaigns:write permission."}],"properties":{"error":{"type":"string","const":"campaigns_not_included"},"message":{"type":"string","const":"Reading campaigns needs a Business or higher plan, or a token with the campaigns:write permission."}},"required":["error","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/campaigns\/instagram\/{igCampaign}":{"post":{"operationId":"customerCampaign.addInstagramUrls","description":"Send the campaign's full list of links each time: links not in the list are\nremoved from the campaign, and every link in it is imported again.\n\nRequires the **Create, update and read campaigns** permission.","summary":"Set an Instagram campaign's Reel URLs","tags":["Campaign Management"],"parameters":[{"name":"igCampaign","in":"path","required":true,"description":"The ig campaign UUID","schema":{"type":["string","null"]}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"links":{"type":"array","description":"List of Instagram Reel URLs to add.","examples":[["https:\/\/www.instagram.com\/reel\/Cx1y2z3A4B5\/","https:\/\/www.instagram.com\/reel\/Ca9b8c7D6E5\/"]],"items":{"type":"string","description":"An Instagram Reel URL.","examples":["https:\/\/www.instagram.com\/reel\/Cx1y2z3A4B5\/"]}}},"required":["links"]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]},{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"No new links to import"}},"required":["success","message"]},{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":["string","null"]}},"required":["success","message"]},{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"Campaign not found"}},"required":["success","message"]}]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"403":{"description":"An error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview.","examples":[""]}},"required":["message"]}}}},"404":{"$ref":"#\/components\/responses\/ModelNotFoundException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"get":{"operationId":"customerCampaign.showInstagram","description":"The same report as for TikTok campaigns, for an Instagram campaign. `views` are the Reels' plays, each\npost has its `type` (`Video`, `Carousel` or `Photo`), there are no saves (null), and `sound_countries` is\nalways empty. `campaign.sound.url` is the audio's page on Instagram.\n\nAvailable with any API token on a Business or higher plan, or with the **Create, update and read campaigns** permission. Returns 404 for a campaign that is not yours.","summary":"Get an Instagram campaign report","tags":["Campaign Management"],"parameters":[{"name":"igCampaign","in":"path","required":true,"description":"The campaign `uuid`.","schema":{"type":"string"},"example":"4c8e2a7d-1f3b-4e9a-b6d5-0a2c8e7f1b93"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"campaign":{"uuid":"4c8e2a7d-1f3b-4e9a-b6d5-0a2c8e7f1b93","name":"Reels launch","platform":"instagram","start_date":"2026-10-01","end_date":null,"sound":{"id":"1234567890","title":"Example song","artist":"Example artist","url":"https:\/\/www.instagram.com\/reels\/audio\/1234567890\/","cover_url":"https:\/\/assets.tokchart.com\/ig_sounds_imgs\/1234567890"},"archived":false,"created_at":"2026-09-30T12:00:00+00:00","updated_at":"2026-10-20T08:01:00+00:00","status":"live","updating":false,"stats_updated_at":"2026-10-20T08:00:00+00:00","share_url":"https:\/\/tokchart.com\/campaigns\/instagram\/4c8e2a7d-1f3b-4e9a-b6d5-0a2c8e7f1b93"},"totals":{"posts":12,"creators":12,"views":640300,"likes":41200,"comments":980,"shares":1520,"saves":null,"engagement_rate":6.42},"last_day":{"views":18400,"likes":1210,"comments":22,"shares":40},"sound_videos":null,"sound_countries":[],"links":{"submitted":12,"added":12,"checking":0,"failed":0},"posts":[{"url":"https:\/\/www.instagram.com\/reel\/Cx1y2z3A4B5","status":"added","unavailable":false,"type":"Video","posted_at":"2026-10-02T15:20:00+00:00","cover_url":"https:\/\/assets.tokchart.com\/ig_reels_imgs\/Cx1y2z3A4B5","creator":{"handle":"creator","profile_url":"https:\/\/www.instagram.com\/creator","country":"GB","followers":88000},"stats":{"views":120400,"likes":9100,"comments":140,"shares":310,"saves":null,"engagement_rate":7.94,"views_to_followers":136.82}}],"daily":[{"date":"2026-10-20","views":640300,"likes":41200,"comments":980,"shares":1520}]}],"properties":{"campaign":{"type":"string"},"totals":{"type":"object","properties":{"posts":{"type":"integer","minimum":0},"creators":{"type":"integer","minimum":0},"views":{"type":"integer"},"likes":{"type":["integer","null"]},"comments":{"type":["integer","null"]},"shares":{"type":["integer","null"]},"saves":{"type":["integer","null"]},"engagement_rate":{"type":["number","null"]}},"required":["posts","creators","views","likes","comments","shares","saves","engagement_rate"]},"last_day":{"type":"string"},"sound_videos":{"type":["object","null"],"properties":{"start":{"type":"string"},"now":{"type":"string"},"change_percent":{"type":["number","null"]},"daily":{"type":"array","items":{}}},"required":["start","now","change_percent","daily"]},"sound_countries":{"type":"array","items":{}},"links":{"type":"object","properties":{"submitted":{"type":"integer","minimum":0},"added":{"type":"integer","minimum":0},"checking":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0}},"required":["submitted","added","checking","failed"]},"posts":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"status":{"type":"string"},"unavailable":{"type":"boolean"},"type":{"type":["string","null"]},"posted_at":{"type":"null"},"cover_url":{"type":["string","null"]},"creator":{"type":["object","null"],"properties":{"handle":{"type":"string"},"profile_url":{"type":"string"},"country":{"type":["string","null"]},"followers":{"type":["integer","null"]}},"required":["handle","profile_url","country","followers"]},"stats":{"type":["object","null"],"properties":{"views":{"type":["integer","null"]},"likes":{"type":["integer","null"]},"comments":{"type":["integer","null"]},"shares":{"type":["integer","null"]},"saves":{"type":["integer","null"]},"engagement_rate":{"type":["number","null"]},"views_to_followers":{"type":["number","null"]}},"required":["views","likes","comments","shares","saves","engagement_rate","views_to_followers"]}},"required":["url","status","unavailable","type","posted_at","cover_url","creator","stats"]}},"daily":{"type":"array","items":{"type":"string"}}},"required":["campaign","totals","last_day","sound_videos","sound_countries","links","posts","daily"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"campaign_not_found","message":"You have no campaign with this UUID."}],"properties":{"error":{"type":"string","const":"campaign_not_found"},"message":{"type":"string","const":"You have no campaign with this UUID."}},"required":["error","message"]}}}},"403":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"campaigns_not_included","message":"Reading campaigns needs a Business or higher plan, or a token with the campaigns:write permission."}],"properties":{"error":{"type":"string","const":"campaigns_not_included"},"message":{"type":"string","const":"Reading campaigns needs a Business or higher plan, or a token with the campaigns:write permission."}},"required":["error","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/campaigns":{"get":{"operationId":"customerCampaign.index","description":"Your TikTok and Instagram campaigns, newest first. Use a campaign's `platform` and `uuid` to read its\nreport, or to set its links.\n\n`posts_count` is every link in the campaign, including links still being checked or that failed.\n`archived` campaigns are listed too, and no longer update.\n`latest_stats` are the campaign's totals at its latest stats update (`captured_at`), null before the\nfirst one. Instagram campaigns have no saves.\n\nAvailable with any API token on a Business or higher plan, or with the **Create, update and read campaigns** permission.","summary":"List campaigns","tags":["Campaign Management"],"parameters":[{"name":"platform","in":"query","description":"Only `tiktok` or only `instagram` campaigns.","schema":{"type":"string"},"example":"tiktok"},{"name":"page","in":"query","description":"Page number (starting from 1).","schema":{"type":"integer","default":1},"example":1},{"name":"per_page","in":"query","description":"Campaigns per page, from 1 to 100.","schema":{"type":"integer","default":50},"example":50}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":[{"uuid":"9b2f6c1e-3d4a-4f8b-a1c2-7e5d9f0b3a68","name":"Summer Music Campaign 2026","platform":"tiktok","start_date":"2026-10-01","end_date":"2026-10-31","sound":{"id":"7123456789012345678","title":"Example song","artist":"Example artist","url":"https:\/\/www.tiktok.com\/music\/example-song-7123456789012345678","tiktok_url":"https:\/\/www.tiktok.com\/music\/example-song-7123456789012345678"},"archived":false,"created_at":"2026-09-28T10:15:00+00:00","updated_at":"2026-10-20T08:02:11+00:00","posts_count":42,"latest_stats":{"views":1834200,"likes":210450,"comments":3120,"shares":8410,"saves":15230,"engagement_rate":11.87,"captured_at":"2026-10-20T08:00:00+00:00"}}],"meta":{"page":1,"per_page":50,"total":1,"last_page":1}}],"properties":{"data":{"type":"array","items":{"type":"string"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"last_page":{"type":"integer"}},"required":["page","per_page","total","last_page"]}},"required":["data","meta"]}}}},"403":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"campaigns_not_included","message":"Reading campaigns needs a Business or higher plan, or a token with the campaigns:write permission."}],"properties":{"error":{"type":"string","const":"campaigns_not_included"},"message":{"type":"string","const":"Reading campaigns needs a Business or higher plan, or a token with the campaigns:write permission."}},"required":["error","message"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/radar":{"post":{"operationId":"radar.store","description":"Creates a Radar from at least one genre or hashtag, and its sounds appear once tracking has started.\nRequires the **Create, update and archive Radars** permission and active Radar access.","summary":"Create a Radar","tags":["Discovery API"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Your plan sets how many Radars can be active (20 by default), including Radars created in the dashboard.","examples":["US Pop Discovery"],"maxLength":255},"genres":{"type":"array","description":"Genre slugs from the Radar genre catalogue. Send at least one genre or hashtag.\n\nSupported genres:\n- `discovery` \u2014 General discovery\n- `electronic` \u2014 Electronic \/ Dance\n- `hiphop` \u2014 Hip-Hop \/ Rap\n- `rnb` \u2014 R&B \/ Soul\n- `pop` \u2014 Pop\n- `indie` \u2014 Indie \/ Alternative\n- `singer-songwriter` \u2014 Singer-Songwriter \/ Folk\n- `country` \u2014 Country\n- `afrobeats` \u2014 Afrobeats \/ Amapiano\n- `christian` \u2014 Christian \/ Gospel\n- `latin` \u2014 Latin\n- `producer` \u2014 Producers \/ Beatmakers","examples":[["pop"]],"items":{"type":"string","maxLength":100,"enum":["discovery","electronic","hiphop","rnb","pop","indie","singer-songwriter","country","afrobeats","christian","latin","producer"]}},"hashtags":{"type":"array","description":"Custom hashtags, with or without a leading #. Duplicates are removed. Your plan sets how many a Radar can\nfollow (25 by default).","examples":[["newmusic"]],"items":{"type":"string","maxLength":100},"maxItems":25},"countries":{"type":"array","description":"Optional audience countries. Use the listed codes or country names. Omit this field or send an empty array for all countries. A value that matches no country returns 422 and names it. `GB` and `UK` both mean the United Kingdom, which responses show as `UK`.\n\nSupported countries:\n- `AF` \u2014 Afghanistan\n- `AL` \u2014 Albania\n- `DZ` \u2014 Algeria\n- `AS` \u2014 American Samoa\n- `AD` \u2014 Andorra\n- `AO` \u2014 Angola\n- `AI` \u2014 Anguilla\n- `AG` \u2014 Antigua and Barbuda\n- `AR` \u2014 Argentina\n- `AM` \u2014 Armenia\n- `AW` \u2014 Aruba\n- `AU` \u2014 Australia\n- `AT` \u2014 Austria\n- `AZ` \u2014 Azerbaijan\n- `BS` \u2014 Bahamas\n- `BH` \u2014 Bahrain\n- `BD` \u2014 Bangladesh\n- `BB` \u2014 Barbados\n- `BY` \u2014 Belarus\n- `BE` \u2014 Belgium\n- `BZ` \u2014 Belize\n- `BJ` \u2014 Benin\n- `BM` \u2014 Bermuda\n- `BT` \u2014 Bhutan\n- `BO` \u2014 Bolivia\n- `BQ` \u2014 Bonaire, Sint Eustatius and Saba\n- `BA` \u2014 Bosnia and Herzegovina\n- `BW` \u2014 Botswana\n- `BV` \u2014 Bouvet Island\n- `BR` \u2014 Brazil\n- `IO` \u2014 British Indian Ocean Territory\n- `BN` \u2014 Brunei Darussalam\n- `BG` \u2014 Bulgaria\n- `BF` \u2014 Burkina Faso\n- `BI` \u2014 Burundi\n- `CV` \u2014 Cabo Verde\n- `KH` \u2014 Cambodia\n- `CM` \u2014 Cameroon\n- `CA` \u2014 Canada\n- `KY` \u2014 Cayman Islands\n- `CF` \u2014 Central African Republic\n- `TD` \u2014 Chad\n- `CL` \u2014 Chile\n- `CN` \u2014 China\n- `CX` \u2014 Christmas Island\n- `CC` \u2014 Cocos (Keeling) Islands\n- `CO` \u2014 Colombia\n- `KM` \u2014 Comoros\n- `CG` \u2014 Congo\n- `CD` \u2014 Congo, Democratic Republic\n- `CK` \u2014 Cook Islands\n- `CR` \u2014 Costa Rica\n- `HR` \u2014 Croatia\n- `CU` \u2014 Cuba\n- `CW` \u2014 Cura\u00e7ao\n- `CY` \u2014 Cyprus\n- `CZ` \u2014 Czech Republic\n- `CI` \u2014 C\u00f4te d'Ivoire\n- `DK` \u2014 Denmark\n- `DJ` \u2014 Djibouti\n- `DM` \u2014 Dominica\n- `DO` \u2014 Dominican Republic\n- `EC` \u2014 Ecuador\n- `EG` \u2014 Egypt\n- `SV` \u2014 El Salvador\n- `GQ` \u2014 Equatorial Guinea\n- `ER` \u2014 Eritrea\n- `EE` \u2014 Estonia\n- `SZ` \u2014 Eswatini\n- `ET` \u2014 Ethiopia\n- `FK` \u2014 Falkland Islands (Malvinas)\n- `FO` \u2014 Faroe Islands\n- `FJ` \u2014 Fiji\n- `FI` \u2014 Finland\n- `FR` \u2014 France\n- `GF` \u2014 French Guiana\n- `PF` \u2014 French Polynesia\n- `TF` \u2014 French Southern Territories\n- `GA` \u2014 Gabon\n- `GM` \u2014 Gambia\n- `GE` \u2014 Georgia\n- `DE` \u2014 Germany\n- `GH` \u2014 Ghana\n- `GI` \u2014 Gibraltar\n- `GR` \u2014 Greece\n- `GL` \u2014 Greenland\n- `GD` \u2014 Grenada\n- `GP` \u2014 Guadeloupe\n- `GU` \u2014 Guam\n- `GT` \u2014 Guatemala\n- `GG` \u2014 Guernsey\n- `GN` \u2014 Guinea\n- `GW` \u2014 Guinea-Bissau\n- `GY` \u2014 Guyana\n- `HT` \u2014 Haiti\n- `HM` \u2014 Heard Island and McDonald Islands\n- `VA` \u2014 Holy See\n- `HN` \u2014 Honduras\n- `HK` \u2014 Hong Kong\n- `HU` \u2014 Hungary\n- `IS` \u2014 Iceland\n- `IN` \u2014 India\n- `ID` \u2014 Indonesia\n- `IR` \u2014 Iran\n- `IQ` \u2014 Iraq\n- `IE` \u2014 Ireland\n- `IM` \u2014 Isle of Man\n- `IL` \u2014 Israel\n- `IT` \u2014 Italy\n- `JM` \u2014 Jamaica\n- `JP` \u2014 Japan\n- `JE` \u2014 Jersey\n- `JO` \u2014 Jordan\n- `KZ` \u2014 Kazakstan\n- `KE` \u2014 Kenya\n- `KI` \u2014 Kiribati\n- `XK` \u2014 Kosovo\n- `KW` \u2014 Kuwait\n- `KG` \u2014 Kyrgyzstan\n- `LA` \u2014 Lao\n- `LV` \u2014 Latvia\n- `LB` \u2014 Lebanon\n- `LS` \u2014 Lesotho\n- `LR` \u2014 Liberia\n- `LY` \u2014 Libya\n- `LI` \u2014 Liechtenstein\n- `LT` \u2014 Lithuania\n- `LU` \u2014 Luxembourg\n- `MO` \u2014 Macao\n- `MG` \u2014 Madagascar\n- `MW` \u2014 Malawi\n- `MY` \u2014 Malaysia\n- `MV` \u2014 Maldives\n- `ML` \u2014 Mali\n- `MT` \u2014 Malta\n- `MH` \u2014 Marshall Islands\n- `MQ` \u2014 Martinique\n- `MR` \u2014 Mauritania\n- `MU` \u2014 Mauritius\n- `YT` \u2014 Mayotte\n- `MX` \u2014 Mexico\n- `FM` \u2014 Micronesia\n- `MD` \u2014 Moldova\n- `MC` \u2014 Monaco\n- `MN` \u2014 Mongolia\n- `ME` \u2014 Montenegro\n- `MS` \u2014 Montserrat\n- `MA` \u2014 Morocco\n- `MZ` \u2014 Mozambique\n- `MM` \u2014 Myanmar\n- `NA` \u2014 Namibia\n- `NR` \u2014 Nauru\n- `NP` \u2014 Nepal\n- `NL` \u2014 Netherlands\n- `NC` \u2014 New Caledonia\n- `NZ` \u2014 New Zealand\n- `NI` \u2014 Nicaragua\n- `NE` \u2014 Niger\n- `NG` \u2014 Nigeria\n- `NU` \u2014 Niue\n- `NF` \u2014 Norfolk Island\n- `KP` \u2014 North Korea\n- `MK` \u2014 North Macedonia\n- `MP` \u2014 Northern Mariana Islands\n- `NO` \u2014 Norway\n- `OM` \u2014 Oman\n- `PK` \u2014 Pakistan\n- `PW` \u2014 Palau\n- `PS` \u2014 Palestine\n- `PA` \u2014 Panama\n- `PG` \u2014 Papua New Guinea\n- `PY` \u2014 Paraguay\n- `PE` \u2014 Peru\n- `PH` \u2014 Philippines\n- `PN` \u2014 Pitcairn\n- `PL` \u2014 Poland\n- `PT` \u2014 Portugal\n- `PR` \u2014 Puerto Rico\n- `QA` \u2014 Qatar\n- `RO` \u2014 Romania\n- `RU` \u2014 Russia\n- `RW` \u2014 Rwanda\n- `RE` \u2014 R\u00e9union\n- `BL` \u2014 Saint Barth\u00e9lemy\n- `SH` \u2014 Saint Helena, Ascension and Tristan da Cunha\n- `KN` \u2014 Saint Kitts and Nevis\n- `LC` \u2014 Saint Lucia\n- `MF` \u2014 Saint Martin (French part)\n- `PM` \u2014 Saint Pierre and Miquelon\n- `VC` \u2014 Saint Vincent and the Grenadines\n- `WS` \u2014 Samoa\n- `SM` \u2014 San Marino\n- `ST` \u2014 Sao Tome and Principe\n- `SA` \u2014 Saudi Arabia\n- `SN` \u2014 Senegal\n- `RS` \u2014 Serbia\n- `SC` \u2014 Seychelles\n- `SL` \u2014 Sierra Leone\n- `SG` \u2014 Singapore\n- `SX` \u2014 Sint Maarten (Dutch part)\n- `SK` \u2014 Slovakia\n- `SI` \u2014 Slovenia\n- `SB` \u2014 Solomon Islands\n- `SO` \u2014 Somalia\n- `ZA` \u2014 South Africa\n- `GS` \u2014 South Georgia and the South Sandwich Islands\n- `KR` \u2014 South Korea\n- `SS` \u2014 South Sudan\n- `ES` \u2014 Spain\n- `LK` \u2014 Sri Lanka\n- `SD` \u2014 Sudan\n- `SR` \u2014 Suriname\n- `SJ` \u2014 Svalbard and Jan Mayen\n- `SE` \u2014 Sweden\n- `CH` \u2014 Switzerland\n- `SY` \u2014 Syrian Arab Republic\n- `TW` \u2014 Taiwan\n- `TJ` \u2014 Tajikistan\n- `TZ` \u2014 Tanzania\n- `TH` \u2014 Thailand\n- `TL` \u2014 Timor-Leste\n- `TG` \u2014 Togo\n- `TK` \u2014 Tokelau\n- `TO` \u2014 Tonga\n- `TT` \u2014 Trinidad and Tobago\n- `TN` \u2014 Tunisia\n- `TR` \u2014 Turkey\n- `TM` \u2014 Turkmenistan\n- `TC` \u2014 Turks and Caicos Islands\n- `TV` \u2014 Tuvalu\n- `UG` \u2014 Uganda\n- `UA` \u2014 Ukraine\n- `AE` \u2014 United Arab Emirates\n- `UK` \u2014 United Kingdom\n- `US` \u2014 United States\n- `UM` \u2014 United States Minor Outlying Islands\n- `UY` \u2014 Uruguay\n- `UZ` \u2014 Uzbekistan\n- `VU` \u2014 Vanuatu\n- `VE` \u2014 Venezuela\n- `VN` \u2014 Vietnam\n- `VG` \u2014 Virgin Islands (British)\n- `VI` \u2014 Virgin Islands (U.S.)\n- `WF` \u2014 Wallis and Futuna\n- `EH` \u2014 Western Sahara\n- `YE` \u2014 Yemen\n- `ZM` \u2014 Zambia\n- `ZW` \u2014 Zimbabwe\n- `AX` \u2014 \u00c5land Islands","examples":[["US"]],"items":{"type":"string","maxLength":100}}},"required":["name"]}}}},"responses":{"201":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"radar":{"id":"018f77f0-3490-7c21-8f5f-a90548c5bd2f","name":"US Pop Discovery","status":"ready","genres":["pop"],"hashtags":["newmusic"],"countries":["US"]}}],"properties":{"radar":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["mixed_attention","failed","empty","preparing","ready"]},"genres":{"type":"array","items":{}},"hashtags":{"type":"array","items":{}},"countries":{"type":"array","items":{}}},"required":["id","name","status","genres","hashtags","countries"]}},"required":["radar"]}}}},"403":{"description":"An error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview.","examples":[""]}},"required":["message"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"get":{"operationId":"radar.index","description":"Returns every active Radar on your account, newest first, including Radars\ncreated in the dashboard. Archived Radars are left out. Read a Radar's\nsounds with \"Get sounds from a Radar\".\n\nRequires the **Read Radar sounds** permission and active Radar access.","summary":"List your Radars","tags":["Discovery API"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":[{"id":"018f77f0-3490-7c21-8f5f-a90548c5bd2f","name":"US Pop Discovery","status":"ready","genres":["pop"],"hashtags":["newmusic"],"countries":["US"]}]}],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["mixed_attention","failed","empty","preparing","ready"]},"genres":{"type":"array","items":{}},"hashtags":{"type":"array","items":{}},"countries":{"type":"array","items":{}}},"required":["id","name","status","genres","hashtags","countries"]}}},"required":["data"]}}}},"403":{"description":"An error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview.","examples":[""]}},"required":["message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/radar\/{radar}\/sounds":{"get":{"operationId":"radar.sounds","description":"Returns the sounds currently matching a Radar, leaving out any you've hidden.\nRequires the **Read Radar sounds** permission and active Radar access.","summary":"Get sounds from a Radar","tags":["Discovery API"],"parameters":[{"name":"genres[]","in":"query","schema":{"type":"array","enum":["pop","dance-pop","synth-pop","indie pop","hyperpop","k-pop","j-pop","c-pop","southeast asian pop","schlager","chanson","russian pop","turkish pop","hip hop","trap","drill","uk drill","uk rap","cloud rap","gangsta rap","phonk","pop rap","latin rap","french rap","christian rap","r&b","soul","funk","disco","edm","house","deep house","tech house","afro house","techno","hardtekk","trance","hardstyle","drum and bass","uk garage","dubstep","breakbeat","jersey club","ambient","downtempo","idm","chiptune","industrial","funkot","rock","alternative rock","indie rock","pop rock","punk","pop punk","psychedelic rock","folk rock","j-rock","metal","nu metal","metalcore","extreme metal","latin pop","reggaeton","regional mexican","corridos","cumbia","bachata","salsa","merengue","vallenato","bolero","latin rock","baile funk","sertanejo","forr\u00f3","pagode","mpb","afrobeats","afrobeat","amapiano","gqom","african dancehall","kizomba","reggae","dancehall","soca","country","country pop","bluegrass","folk","celtic","jazz","swing","blues","classical","score","bollywood","punjabi","regional indian","devotional","arabic pop","rai","mena hip hop","islamic","persian","mizrahi","gospel","worship","flamenco","european folk","children's","holiday","comedy"],"items":{"type":"string","enum":["pop","dance-pop","synth-pop","indie pop","hyperpop","k-pop","j-pop","c-pop","southeast asian pop","schlager","chanson","russian pop","turkish pop","hip hop","trap","drill","uk drill","uk rap","cloud rap","gangsta rap","phonk","pop rap","latin rap","french rap","christian rap","r&b","soul","funk","disco","edm","house","deep house","tech house","afro house","techno","hardtekk","trance","hardstyle","drum and bass","uk garage","dubstep","breakbeat","jersey club","ambient","downtempo","idm","chiptune","industrial","funkot","rock","alternative rock","indie rock","pop rock","punk","pop punk","psychedelic rock","folk rock","j-rock","metal","nu metal","metalcore","extreme metal","latin pop","reggaeton","regional mexican","corridos","cumbia","bachata","salsa","merengue","vallenato","bolero","latin rock","baile funk","sertanejo","forr\u00f3","pagode","mpb","afrobeats","afrobeat","amapiano","gqom","african dancehall","kizomba","reggae","dancehall","soca","country","country pop","bluegrass","folk","celtic","jazz","swing","blues","classical","score","bollywood","punjabi","regional indian","devotional","arabic pop","rai","mena hip hop","islamic","persian","mizrahi","gospel","worship","flamenco","european folk","children's","holiday","comedy"]}}},{"name":"audio_content[]","in":"query","schema":{"type":"array","enum":["music","speech_over_music","not_music"],"items":{"type":"string","enum":["music","speech_over_music","not_music"]}}},{"name":"radar","in":"path","required":true,"description":"UUID of a Radar owned by the authenticated user.","schema":{"type":"string"},"example":"018f77f0-3490-7c21-8f5f-a90548c5bd2f"},{"name":"page","in":"query","description":"Page number (starting from 1).","schema":{"type":"integer","default":1},"example":1},{"name":"per_page","in":"query","description":"Number of sounds per page (1\u20131000). Suggested sizes: 50, 100, 250, 500, 750, 1000. Defaults to 50.","schema":{"type":"integer","default":50},"example":50},{"name":"sound_type","in":"query","description":"Filter by sound type: commercial (Catalog Sound), ugc_original (UGC Original Audio), or ugc_music (UGC Contains Music). Omit to include all types.","schema":{"type":"string"},"example":"ugc_original"},{"name":"original_artists","in":"query","description":"When true, hides sounds where an account re-uses another artist's song, and returns music only unless `audio_content` is given. Beta.","schema":{"type":"boolean"},"example":true}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"radar":{"id":"018f77f0-3490-7c21-8f5f-a90548c5bd2f","name":"US Pop and R&B Discovery","status":"ready","genres":["pop","rnb"],"hashtags":["newmusic"],"countries":["US"]},"data":[{"sound_id":"7290123456789012345","title":"Original sound","sound_type":"ugc_original","spotify_url":"https:\/\/open.spotify.com\/track\/4iV5W9uYEdYUVa79Axb7Rh","matched_song":{"track_id":"018f77f0-3490-5c21-8f5f-a90548c5bd2f","spotify_uri":"spotify:track:4iV5W9uYEdYUVa79Axb7Rh","title":"Example Song","artists":[{"spotify_uri":"spotify:artist:06HL4z0CvFAxyc27GXpf02","name":"Example Artist","spotify_id":"06HL4z0CvFAxyc27GXpf02"}],"spotify_track_id":"4iV5W9uYEdYUVa79Axb7Rh","isrc":"USSM12600001","release_date":"2026-08-01","label":"Columbia","genres":["Pop"]},"cover_url":"https:\/\/assets.tokchart.com\/images\/sounds_data\/cover\/b4\/b4bcab16ef4a01dc.webp","tiktok_url":"https:\/\/www.tiktok.com\/music\/-7290123456789012345","record_label":"Columbia","matched_genres":["pop"],"uploaded_at":"2026-08-26T10:30:00+00:00","latest_videos_count":482,"previous_videos_count":415,"avg_daily_delta":67,"avg_daily_delta_percentage_growth":16.14,"views_count":1240000,"likes_count":93000,"comments_count":3200,"shares_count":8100,"engagement_rate":0.083,"author":{"account_id":"987654321","name":"Example Artist","username":"exampleartist","followers_count":18200,"tiktok_url":"https:\/\/www.tiktok.com\/@exampleartist"},"daily_stats":[{"date":"2026-08-30","videos_count":415},{"date":"2026-08-31","videos_count":482}],"country_signals":[{"code":"US","name":"United States","tier":"Strong"}],"stats_as_of":"2026-08-31T08:00:00+00:00","bookmarked":false}],"meta":{"page":1,"per_page":50,"total":126,"last_page":3}}],"properties":{"radar":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["mixed_attention","failed","empty","preparing","ready"]},"genres":{"type":"array","items":{}},"hashtags":{"type":"array","items":{}},"countries":{"type":"array","items":{}}},"required":["id","name","status","genres","hashtags","countries"]},"data":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"sound_id":{"type":"string"},"title":{"type":"string"},"sound_type":{"type":["string","null"]},"spotify_url":{"type":["string","null"]},"matched_song":{"type":["object","null"],"properties":{"track_id":{"type":"string"},"spotify_uri":{"type":["string","null"]},"title":{"type":"string"},"artists":{"type":"array","items":{"type":"object","properties":{"spotify_uri":{"type":["string","null"]},"name":{"type":"string"},"spotify_id":{"type":["string","null"]}},"required":["spotify_uri","name","spotify_id"]}},"spotify_track_id":{"type":["string","null"]},"isrc":{"type":["string","null"]},"release_date":{"type":["string","null"]},"label":{"type":["string","null"]},"genres":{"type":"array","items":{"type":"string"}}},"required":["track_id","spotify_uri","title","artists","spotify_track_id","isrc","release_date","label","genres"]},"cover_url":{"type":["string","null"]},"tiktok_url":{"type":"string"},"record_label":{"type":["string","null"]},"uploaded_at":{"type":["string","null"]},"latest_videos_count":{"type":"integer"},"previous_videos_count":{"type":"integer"},"avg_daily_delta":{"type":"number"},"avg_daily_delta_percentage_growth":{"type":"number"},"views_count":{"type":"integer"},"likes_count":{"type":"integer"},"comments_count":{"type":"integer"},"shares_count":{"type":"integer"},"engagement_rate":{"type":"number"},"author":{"type":"object","properties":{"account_id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"followers_count":{"type":"integer"},"tiktok_url":{"type":"string"}},"required":["account_id","name","username","followers_count","tiktok_url"]},"daily_stats":{"type":"object","additionalProperties":{"type":"object","properties":{"date":{"type":"string"},"videos_count":{"type":"integer"}},"required":["date","videos_count"]}},"country_signals":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string"}},"required":["code","name","tier"]}},"stats_as_of":{"type":["string","null"]},"bookmarked":{"type":"boolean"},"matched_genres":{"type":"array","items":{"type":"string"}}},"required":["sound_id","title","sound_type","spotify_url","matched_song","cover_url","tiktok_url","record_label","uploaded_at","latest_videos_count","previous_videos_count","avg_daily_delta","avg_daily_delta_percentage_growth","views_count","likes_count","comments_count","shares_count","engagement_rate","author","daily_stats","country_signals","stats_as_of","bookmarked","matched_genres"]},{"type":"object","properties":{"sound_id":{"type":"string"},"title":{"type":"string"},"sound_type":{"type":["string","null"]},"spotify_url":{"type":["string","null"]},"matched_song":{"type":["object","null"],"properties":{"track_id":{"type":"string"},"spotify_uri":{"type":["string","null"]},"title":{"type":"string"},"artists":{"type":"array","items":{"type":"object","properties":{"spotify_uri":{"type":["string","null"]},"name":{"type":"string"},"spotify_id":{"type":["string","null"]}},"required":["spotify_uri","name","spotify_id"]}},"spotify_track_id":{"type":["string","null"]},"isrc":{"type":["string","null"]},"release_date":{"type":["string","null"]},"label":{"type":["string","null"]},"genres":{"type":"array","items":{"type":"string"}}},"required":["track_id","spotify_uri","title","artists","spotify_track_id","isrc","release_date","label","genres"]},"cover_url":{"type":["string","null"]},"tiktok_url":{"type":"string"},"record_label":{"type":["string","null"]},"uploaded_at":{"type":["string","null"]},"latest_videos_count":{"type":"integer"},"previous_videos_count":{"type":"integer"},"avg_daily_delta":{"type":"number"},"avg_daily_delta_percentage_growth":{"type":"number"},"views_count":{"type":"integer"},"likes_count":{"type":"integer"},"comments_count":{"type":"integer"},"shares_count":{"type":"integer"},"engagement_rate":{"type":"number"},"author":{"type":"object","properties":{"account_id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"followers_count":{"type":"integer"},"tiktok_url":{"type":"string"}},"required":["account_id","name","username","followers_count","tiktok_url"]},"daily_stats":{"type":"object","additionalProperties":{"type":"object","properties":{"date":{"type":"string"},"videos_count":{"type":"integer"}},"required":["date","videos_count"]}},"country_signals":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string"}},"required":["code","name","tier"]}},"stats_as_of":{"type":["string","null"]},"bookmarked":{"type":"boolean"}},"required":["sound_id","title","sound_type","spotify_url","matched_song","cover_url","tiktok_url","record_label","uploaded_at","latest_videos_count","previous_videos_count","avg_daily_delta","avg_daily_delta_percentage_growth","views_count","likes_count","comments_count","shares_count","engagement_rate","author","daily_stats","country_signals","stats_as_of","bookmarked"]}]}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"last_page":{"type":"integer"}},"required":["page","per_page","total","last_page"]}},"required":["radar","data","meta"]}}}},"403":{"description":"An error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview.","examples":[""]}},"required":["message"]}}}},"404":{"$ref":"#\/components\/responses\/ModelNotFoundException"},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"x-response-fields":[{"name":"sound_type","description":"`commercial` (Catalog sound), `ugc_original` (UGC original audio) or `ugc_music` (UGC that contains music), as in the dashboard."},{"name":"spotify_url","description":"A Spotify track link, or null when there is none. It can appear before the song's artist or label details."},{"name":"matched_song","description":"The song linked to the sound, or null when it has none."},{"name":"matched_song.track_id","description":"Works with `\/tiktok\/audio\/tracks\/{track_id}\/sounds`."},{"name":"matched_song.artists[].spotify_id","description":"The artist's Spotify ID, or null when it's unknown or the name is shared by more than one Spotify artist."},{"name":"matched_song.spotify_track_id","description":"The ID in `spotify_url`. A sound can have a `spotify_url` and a null `matched_song`."},{"name":"matched_song.isrc","description":"Null when unknown."},{"name":"matched_song.release_date","description":"`YYYY-MM-DD`, or null when unknown."},{"name":"matched_song.label","description":"The label from the release details, or null when unknown."},{"name":"cover_url","description":"The sound's cover image, or null when there is none. For display and attribution only."},{"name":"tiktok_url","description":"The sound's TikTok page. For display and attribution only."},{"name":"record_label","description":"The record label of the sound's matched song, else the label Spotify reports for the album in `spotify_url`, else null. It's returned as reported, so it can be an imprint, a distributor or the artist's own name."},{"name":"matched_genres","description":"Only returned when the Radar has more than one genre. The Radar's genres whose curated hashtags matched the sound, which isn't a musical classification, so several can match. Empty when only custom hashtags matched."},{"name":"latest_videos_count","description":"Total videos at the latest count. It can be newer than the growth interval, so don't use it to recalculate daily growth."},{"name":"previous_videos_count","description":"Total videos at the start of the growth interval."},{"name":"avg_daily_delta","description":"New videos per day, averaged over the latest growth interval of at least one day."},{"name":"avg_daily_delta_percentage_growth","description":"`avg_daily_delta` divided by `previous_videos_count`, times 100, rounded to two decimals. 0 when `previous_videos_count` is 0."}]}},"\/radar\/{radar}\/artists":{"get":{"operationId":"radar.artists","description":"Developing artists whose original songs took off on TikTok: songs we first saw at 20 to 500 videos that have\nsince reached 1,000, grouped by the account that uploaded them, most videos gained first. The Radar's countries\nare the country of the artist's TikTok account. On a genre Radar a song counts only when our model hears one of\nits genres. Fan, lyric, AI and anonymous accounts, and covers or remixes of someone else's bigger song, are left\nout. Under 250,000 followers by default. Refreshed daily. Requires the **Read Radar sounds** permission and active Radar access.","summary":"Get artists from a Radar","tags":["Discovery API"],"parameters":[{"name":"radar","in":"path","required":true,"description":"UUID of a Radar owned by the authenticated user.","schema":{"type":"string"},"example":"018f77f0-3490-7c21-8f5f-a90548c5bd2f"},{"name":"page","in":"query","description":"Page number (starting from 1).","schema":{"type":"integer","default":1},"example":1},{"name":"per_page","in":"query","description":"Number of artists per page (1\u2013100). Defaults to 50.","schema":{"type":"integer","default":50},"example":50},{"name":"months","in":"query","description":"How far back the songs were first spotted: 1, 3, 6 or 12 months. Defaults to 6.","schema":{"type":"integer","default":6},"example":6},{"name":"own_songs","in":"query","description":"When true (the default), only songs released under the artist's own name count, and fan pages, label channels, AI music projects and covers are left out. False counts every original audio they uploaded.","schema":{"type":"boolean","default":true},"example":true},{"name":"min_followers","in":"query","description":"Fewest TikTok followers the artist may have.","schema":{"type":"integer"},"example":1000},{"name":"max_followers","in":"query","description":"Most TikTok followers the artist may have. Defaults to 250,000, so established artists are left out; 0 for no limit.","schema":{"type":"integer","default":250000},"example":100000},{"name":"sort","in":"query","description":"`gained` (most new videos, the default), `fastest` (most new videos a day on one song), `newest` (most recently spotted) or `fewest_followers`.","schema":{"type":"string","default":"gained"},"example":"gained"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"radar":{"id":"018f77f0-3490-7c21-8f5f-a90548c5bd2f","name":"US Pop Discovery","status":"ready","genres":["pop"],"hashtags":["newmusic"],"countries":["US"]},"data":[{"account_id":"7012345678901234567","name":"Example Artist","username":"exampleartist","tiktok_url":"https:\/\/www.tiktok.com\/@exampleartist","avatar_url":"https:\/\/p16-sign.tiktokcdn-us.com\/example.jpeg","followers_count":33600,"country":{"code":"US","name":"United States","flag":"\ud83c\uddfa\ud83c\uddf8"},"songs_count":1,"videos_gained":95395,"best_videos_per_day":1590,"first_spotted_at":"2026-09-11T08:00:00+00:00","own_song":true,"top_song":{"sound_id":"7678402220329372447","title":"Example Song","released_on":"2026-09-19","spotify_url":"https:\/\/open.spotify.com\/track\/4iV5W9uYEdYUVa79Axb7Rh","tiktok_url":"https:\/\/www.tiktok.com\/music\/-7678402220329372447","tokchart_url":"https:\/\/tokchart.com\/dashboard\/tiktok-sound\/7678402220329372447","videos_when_spotted":205,"videos":95600,"spotted_at":"2026-09-11T08:00:00+00:00","genres":["pop"],"daily_videos":[["2026-09-11",205],["2026-09-12",8362]]}}],"meta":{"page":1,"per_page":50,"total":53,"last_page":2,"months":6,"own_songs":true,"refreshed_at":"2026-11-11T04:41:00+00:00"}}],"properties":{"radar":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["mixed_attention","failed","empty","preparing","ready"]},"genres":{"type":"array","items":{}},"hashtags":{"type":"array","items":{}},"countries":{"type":"array","items":{}}},"required":["id","name","status","genres","hashtags","countries"]},"data":{"type":"array","items":{}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"last_page":{"type":"integer"},"months":{"type":"integer"},"own_songs":{"type":"boolean"},"refreshed_at":{"type":["string","null"]}},"required":["page","per_page","total","last_page","months","own_songs","refreshed_at"]}},"required":["radar","data","meta"]}}}},"403":{"description":"An error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview.","examples":[""]}},"required":["message"]}}}},"404":{"$ref":"#\/components\/responses\/ModelNotFoundException"},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"x-response-fields":[{"name":"account_id","description":"The artist's TikTok account id."},{"name":"username","description":"The artist's TikTok handle, or null when TikTok didn't give one."},{"name":"country","description":"The country of the artist's TikTok account (code, name, flag), or null when unknown. It's where the account is registered, which can differ from where the artist is from."},{"name":"songs_count","description":"Distinct songs of theirs we spotted early in the window (one song uploaded several times counts once)."},{"name":"videos_gained","description":"New TikTok videos on those songs since we first spotted each one."},{"name":"best_videos_per_day","description":"The most new videos a day on one of those songs, averaged from first sighting to the latest count."},{"name":"own_song","description":"True when at least one of the songs is released under the artist's own name."},{"name":"top_song","description":"Their song with the most new videos."},{"name":"top_song.title","description":"The released song's title, else the TikTok audio's."},{"name":"top_song.released_on","description":"Release date of the matched song, or null when unknown."},{"name":"top_song.videos_when_spotted","description":"Videos using it when we first saw it (20 to 500)."},{"name":"top_song.daily_videos","description":"Videos using it per day since we spotted it, as [date, videos], at most 60 points."},{"name":"top_song.genres","description":"Genres our model hears in the audio, when it has scored it."}]}},"\/radar\/{radar}":{"get":{"operationId":"radar.show","description":"Returns one active Radar with its saved genres, hashtags and countries.\n\nRequires the **Read Radar sounds** permission and active Radar access. Returns 404\nfor a Radar that is not yours or has been archived.","summary":"Get a Radar","tags":["Discovery API"],"parameters":[{"name":"radar","in":"path","required":true,"description":"UUID of a Radar owned by the authenticated user.","schema":{"type":"string"},"example":"018f77f0-3490-7c21-8f5f-a90548c5bd2f"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"radar":{"id":"018f77f0-3490-7c21-8f5f-a90548c5bd2f","name":"US Pop Discovery","status":"ready","genres":["pop"],"hashtags":["newmusic"],"countries":["US"]}}],"properties":{"radar":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["mixed_attention","failed","empty","preparing","ready"]},"genres":{"type":"array","items":{}},"hashtags":{"type":"array","items":{}},"countries":{"type":"array","items":{}}},"required":["id","name","status","genres","hashtags","countries"]}},"required":["radar"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"radar_not_found","message":"You have no active Radar with this ID."}],"properties":{"error":{"type":"string","const":"radar_not_found"},"message":{"type":"string","const":"You have no active Radar with this ID."}},"required":["error","message"]}}}},"403":{"description":"An error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview.","examples":[""]}},"required":["message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"patch":{"operationId":"radar.update","description":"Changes only the fields you send, and later sound reads use the new settings.\nRequires the **Create, update and archive Radars** permission and active Radar access. Returns 404 for a Radar that is not yours or has\nbeen archived.","summary":"Update a Radar","tags":["Discovery API"],"parameters":[{"name":"radar","in":"path","required":true,"description":"UUID of a Radar owned by the authenticated user.","schema":{"type":"string"},"example":"018f77f0-3490-7c21-8f5f-a90548c5bd2f"}],"requestBody":{"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","examples":["US Pop Discovery"],"maxLength":255},"genres":{"type":"array","description":"Replaces the Radar's genres. It can't be sent with `add_genres` or `remove_genres`, and the Radar must keep\nat least one genre or hashtag.","examples":[["pop"]],"items":{"type":"string","maxLength":100}},"add_genres":{"type":"array","description":"Genre slugs to add.","examples":[["rnb"]],"items":{"type":"string","maxLength":100}},"remove_genres":{"type":"array","description":"Genre slugs to remove. Removals apply first, and removing one the Radar doesn't have is ignored.","examples":[["pop"]],"items":{"type":"string","maxLength":100}},"hashtags":{"type":"array","description":"Replaces the Radar's custom hashtags, with or without a leading #. It can't be sent with `add_hashtags` or\n`remove_hashtags`, and the Radar must keep at least one genre or hashtag.","examples":[["newmusic"]],"items":{"type":"string","maxLength":100}},"add_hashtags":{"type":"array","description":"Hashtags to add, with or without a leading #. Your plan sets how many a Radar can follow (25 by default), and\nnew hashtags start tracking in the background.","examples":[["newartist"]],"items":{"type":"string","maxLength":100}},"remove_hashtags":{"type":"array","description":"Hashtags to remove, with or without a leading #. Removals apply first, and removing one the Radar doesn't have\nis ignored.","examples":[["newmusic"]],"items":{"type":"string","maxLength":100}},"countries":{"type":"array","description":"Replaces the Radar's audience countries, as ISO 3166-1 alpha-2 codes or names. An empty array means all\ncountries. It can't be sent with `add_countries` or `remove_countries`. A value that matches no country\nreturns 422 and names it. `GB` and `UK` both mean the United Kingdom, which responses show as `UK`.","examples":[["US"]],"items":{"type":"string","maxLength":100}},"add_countries":{"type":"array","description":"Audience countries to add, as ISO 3166-1 alpha-2 codes or names.","examples":[["DE"]],"items":{"type":"string","maxLength":100}},"remove_countries":{"type":"array","description":"Audience countries to remove, as ISO 3166-1 alpha-2 codes or names.","examples":[["US"]],"items":{"type":"string","maxLength":100}}}}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"radar":{"id":"018f77f0-3490-7c21-8f5f-a90548c5bd2f","name":"US Pop Discovery","status":"ready","genres":["pop"],"hashtags":["newmusic"],"countries":["US"]}}],"properties":{"radar":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["mixed_attention","failed","empty","preparing","ready"]},"genres":{"type":"array","items":{}},"hashtags":{"type":"array","items":{}},"countries":{"type":"array","items":{}}},"required":["id","name","status","genres","hashtags","countries"]}},"required":["radar"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"radar_not_found","message":"You have no active Radar with this ID."}],"properties":{"error":{"type":"string","const":"radar_not_found"},"message":{"type":"string","const":"You have no active Radar with this ID."}},"required":["error","message"]}}}},"403":{"description":"An error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview.","examples":[""]}},"required":["message"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"delete":{"operationId":"radar.destroy","description":"The same as Delete on the Radar's dashboard page: the Radar stops counting\ntowards your plan's limit and can no longer be read or changed.\n\nRequires the **Create, update and archive Radars** permission and active Radar access. Returns 404\nfor a Radar that is not yours or has already been archived.","summary":"Archive a Radar","tags":["Discovery API"],"parameters":[{"name":"radar","in":"path","required":true,"description":"UUID of a Radar owned by the authenticated user.","schema":{"type":"string"},"example":"018f77f0-3490-7c21-8f5f-a90548c5bd2f"}],"responses":{"204":{"description":"No content"},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"radar_not_found","message":"You have no active Radar with this ID."}],"properties":{"error":{"type":"string","const":"radar_not_found"},"message":{"type":"string","const":"You have no active Radar with this ID."}},"required":["error","message"]}}}},"403":{"description":"An error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview.","examples":[""]}},"required":["message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/trending\/global":{"get":{"operationId":"tikTokAudioTrending.global","description":"Returns a paginated list of trending TikTok audios globally, ordered by chart position.\nRequires the **Read trending TikTok sounds worldwide and Spotify matches** permission.","summary":"Get trending TikTok audio globally","tags":["TikTok Audio Trending"],"parameters":[{"name":"page","in":"query","description":"Page number (starting from 1).","schema":{"type":"integer","default":1},"example":1},{"name":"page_size","in":"query","description":"Number of items per page (max 1000).","schema":{"type":"integer","default":50},"example":1000},{"name":"hashtags","in":"query","description":"Include the top N hashtags for each sound. Max: 10. Omit to exclude hashtags.","schema":{"type":"integer"},"example":3}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"items":[{"chart_index":1,"sound_id":7536694526191127327,"title":"Original sound","author":"creator","tokchart_score":987,"ugc_videos_total":25846806,"ugc_videos_per_day":36111,"ugc_videos_acceleration":1200,"content_type":"music","is_catalog":true,"sound_duration_seconds":31,"views_total":500000000,"likes_total":45000000,"uploaded_at":"2026-06-01 12:34:56","trending_countries":["US","UK"],"trending_countries_ranked":[{"country":"US","rank":3},{"country":"UK","rank":12}],"spotify_url":"https:\/\/open.spotify.com\/track\/4iV5W9uYEdYUVa79Axb7Rh","matched_song":{"track_id":"018f77f0-3490-5c21-8f5f-a90548c5bd2f","spotify_uri":"spotify:track:4iV5W9uYEdYUVa79Axb7Rh","title":"Example Song","artists":[{"spotify_uri":"spotify:artist:06HL4z0CvFAxyc27GXpf02","name":"Example Artist","spotify_id":"06HL4z0CvFAxyc27GXpf02"},{"spotify_uri":null,"name":"Featured Artist","spotify_id":null}],"spotify_track_id":"4iV5W9uYEdYUVa79Axb7Rh","isrc":"USSM12600001","release_date":"2026-05-29","label":"Columbia","genres":["Pop"]},"cover_url":"https:\/\/assets.tokchart.com\/images\/sounds_data\/cover\/ab\/ab7f519e6d45a29a.webp","tiktok_url":"https:\/\/www.tiktok.com\/music\/-7536694526191127327","daily_stats":[{"date":"2026-06-04","videos_count":25810695},{"date":"2026-06-05","videos_count":25846806}],"hashtags":["dance","fyp","viral"]},{"chart_index":2,"sound_id":7536694526191127328,"title":"original sound - creator","author":"creator","tokchart_score":951,"ugc_videos_total":259725,"ugc_videos_per_day":710,"ugc_videos_acceleration":120,"content_type":"original","is_catalog":false,"sound_duration_seconds":18,"views_total":5000000,"likes_total":450000,"uploaded_at":"2026-06-01 12:34:56","trending_countries":["US"],"trending_countries_ranked":[{"country":"US","rank":41}],"spotify_url":null,"matched_song":null,"cover_url":null,"tiktok_url":"https:\/\/www.tiktok.com\/music\/-7536694526191127328","daily_stats":[{"date":"2026-06-03","videos_count":258315},{"date":"2026-06-05","videos_count":259725}],"hashtags":["fyp"]}],"total_items":1000,"page":1,"page_size":1000,"total_pages":1}],"properties":{"items":{"type":"array","prefixItems":[{"type":"object","properties":{"chart_index":{"type":"integer","const":1},"sound_id":{"type":"integer","const":7536694526191127327},"title":{"type":"string","const":"Original sound"},"author":{"type":"string","const":"creator"},"tokchart_score":{"type":"integer","const":987},"ugc_videos_total":{"type":"integer","const":25846806},"ugc_videos_per_day":{"type":"integer","const":36111},"ugc_videos_acceleration":{"type":"integer","const":1200},"content_type":{"type":"string","const":"music"},"is_catalog":{"type":"boolean"},"sound_duration_seconds":{"type":"integer","const":31},"views_total":{"type":"integer","const":500000000},"likes_total":{"type":"integer","const":45000000},"uploaded_at":{"type":"string","const":"2026-06-01 12:34:56"},"trending_countries":{"type":"array","prefixItems":[{"type":"string","const":"US"},{"type":"string","const":"UK"}],"minItems":2,"maxItems":2,"additionalItems":false},"trending_countries_ranked":{"type":"array","prefixItems":[{"type":"object","properties":{"country":{"type":"string","const":"US"},"rank":{"type":"integer","const":3}},"required":["country","rank"]},{"type":"object","properties":{"country":{"type":"string","const":"UK"},"rank":{"type":"integer","const":12}},"required":["country","rank"]}],"minItems":2,"maxItems":2,"additionalItems":false},"spotify_url":{"type":"string"},"matched_song":{"type":"object","properties":{"track_id":{"type":"string","const":"018f77f0-3490-5c21-8f5f-a90548c5bd2f"},"spotify_uri":{"type":"string","const":"spotify:track:4iV5W9uYEdYUVa79Axb7Rh"},"title":{"type":"string","const":"Example Song"},"artists":{"type":"array","prefixItems":[{"type":"object","properties":{"spotify_uri":{"type":"string","const":"spotify:artist:06HL4z0CvFAxyc27GXpf02"},"name":{"type":"string","const":"Example Artist"},"spotify_id":{"type":"string","const":"06HL4z0CvFAxyc27GXpf02"}},"required":["spotify_uri","name","spotify_id"]},{"type":"object","properties":{"spotify_uri":{"type":"null"},"name":{"type":"string","const":"Featured Artist"},"spotify_id":{"type":"null"}},"required":["spotify_uri","name","spotify_id"]}],"minItems":2,"maxItems":2,"additionalItems":false},"spotify_track_id":{"type":"string","const":"4iV5W9uYEdYUVa79Axb7Rh"},"isrc":{"type":"string","const":"USSM12600001"},"release_date":{"type":"string","const":"2026-05-29"},"label":{"type":"string","const":"Columbia"},"genres":{"type":"array","prefixItems":[{"type":"string","const":"Pop"}],"minItems":1,"maxItems":1,"additionalItems":false}},"required":["track_id","spotify_uri","title","artists","spotify_track_id","isrc","release_date","label","genres"]},"cover_url":{"type":"string","const":"https:\/\/assets.tokchart.com\/images\/sounds_data\/cover\/ab\/ab7f519e6d45a29a.webp"},"tiktok_url":{"type":"string","const":"https:\/\/www.tiktok.com\/music\/-7536694526191127327"},"daily_stats":{"type":"array","prefixItems":[{"type":"object","properties":{"date":{"type":"string","const":"2026-06-04"},"videos_count":{"type":"integer","const":25810695}},"required":["date","videos_count"]},{"type":"object","properties":{"date":{"type":"string","const":"2026-06-05"},"videos_count":{"type":"integer","const":25846806}},"required":["date","videos_count"]}],"minItems":2,"maxItems":2,"additionalItems":false},"hashtags":{"type":"array","prefixItems":[{"type":"string","const":"dance"},{"type":"string","const":"fyp"},{"type":"string","const":"viral"}],"minItems":3,"maxItems":3,"additionalItems":false}},"required":["chart_index","sound_id","title","author","tokchart_score","ugc_videos_total","ugc_videos_per_day","ugc_videos_acceleration","content_type","is_catalog","sound_duration_seconds","views_total","likes_total","uploaded_at","trending_countries","trending_countries_ranked","spotify_url","matched_song","cover_url","tiktok_url","daily_stats","hashtags"]},{"type":"object","properties":{"chart_index":{"type":"integer","const":2},"sound_id":{"type":"integer","const":7536694526191127328},"title":{"type":"string","const":"original sound - creator"},"author":{"type":"string","const":"creator"},"tokchart_score":{"type":"integer","const":951},"ugc_videos_total":{"type":"integer","const":259725},"ugc_videos_per_day":{"type":"integer","const":710},"ugc_videos_acceleration":{"type":"integer","const":120},"content_type":{"type":"string","const":"original"},"is_catalog":{"type":"boolean"},"sound_duration_seconds":{"type":"integer","const":18},"views_total":{"type":"integer","const":5000000},"likes_total":{"type":"integer","const":450000},"uploaded_at":{"type":"string","const":"2026-06-01 12:34:56"},"trending_countries":{"type":"array","prefixItems":[{"type":"string","const":"US"}],"minItems":1,"maxItems":1,"additionalItems":false},"trending_countries_ranked":{"type":"array","prefixItems":[{"type":"object","properties":{"country":{"type":"string","const":"US"},"rank":{"type":"integer","const":41}},"required":["country","rank"]}],"minItems":1,"maxItems":1,"additionalItems":false},"spotify_url":{"type":"null"},"matched_song":{"type":"null"},"cover_url":{"type":"null"},"tiktok_url":{"type":"string","const":"https:\/\/www.tiktok.com\/music\/-7536694526191127328"},"daily_stats":{"type":"array","prefixItems":[{"type":"object","properties":{"date":{"type":"string","const":"2026-06-03"},"videos_count":{"type":"integer","const":258315}},"required":["date","videos_count"]},{"type":"object","properties":{"date":{"type":"string","const":"2026-06-05"},"videos_count":{"type":"integer","const":259725}},"required":["date","videos_count"]}],"minItems":2,"maxItems":2,"additionalItems":false},"hashtags":{"type":"array","prefixItems":[{"type":"string","const":"fyp"}],"minItems":1,"maxItems":1,"additionalItems":false}},"required":["chart_index","sound_id","title","author","tokchart_score","ugc_videos_total","ugc_videos_per_day","ugc_videos_acceleration","content_type","is_catalog","sound_duration_seconds","views_total","likes_total","uploaded_at","trending_countries","trending_countries_ranked","spotify_url","matched_song","cover_url","tiktok_url","daily_stats","hashtags"]}],"minItems":2,"maxItems":2,"additionalItems":false},"total_items":{"type":"integer","const":1000},"page":{"type":"integer","const":1},"page_size":{"type":"integer","const":1000},"total_pages":{"type":"integer","const":1}},"required":["items","total_items","page","page_size","total_pages"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"x-response-fields":[{"name":"ugc_videos_total","description":"Total videos using the sound."},{"name":"ugc_videos_per_day","description":"New videos using the sound per day."},{"name":"ugc_videos_acceleration","description":"How fast `ugc_videos_per_day` is changing."},{"name":"content_type","description":"`music` when the sound is matched to a song, `original` when it isn't."},{"name":"is_catalog","description":"True for Catalog sounds, false for UGC sounds. False with `content_type` `music` is UGC that contains music."},{"name":"trending_countries","description":"The countries where the sound is trending, strongest first."},{"name":"trending_countries_ranked","description":"The same countries, with the sound's chart position in each."},{"name":"spotify_url","description":"A Spotify track link, or null when there is none."},{"name":"matched_song","description":"The song linked to the sound, or null when it has none."},{"name":"matched_song.track_id","description":"Works with `\/tiktok\/audio\/tracks\/{track_id}\/sounds`."},{"name":"matched_song.artists[].spotify_id","description":"The artist's Spotify ID, or null when it's unknown or the name is shared by more than one Spotify artist."},{"name":"matched_song.spotify_track_id","description":"The ID in `spotify_url`. A sound can have a `spotify_url` and a null `matched_song`."},{"name":"matched_song.isrc","description":"Null when unknown."},{"name":"matched_song.release_date","description":"`YYYY-MM-DD`, or null when unknown."},{"name":"matched_song.label","description":"Null when unknown."},{"name":"cover_url","description":"The sound's cover image, or null when there is none. For display and attribution only."},{"name":"tiktok_url","description":"The sound's TikTok page. For display and attribution only."},{"name":"daily_stats","description":"The sound's total videos over the last 14 days, oldest first. Only days we have a figure are included, so dates can have gaps and the list can be empty."},{"name":"hashtags","description":"The top hashtags used with the sound. Only returned when you pass the `hashtags` parameter."}]}},"\/tiktok\/audio\/trending\/country\/{code}":{"get":{"operationId":"tikTokAudioTrending.country","description":"Returns a paginated list of trending TikTok audios for a specific country, ordered by chart position.\nRequires the Read trending TikTok sounds permission for the requested country.","summary":"Get trending TikTok audio by country","tags":["TikTok Audio Trending"],"parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code, in any case. GB and UK both mean the United Kingdom.\n\nSupported codes:\n- DZ (Algeria)\n- AR (Argentina)\n- AU (Australia)\n- AT (Austria)\n- BD (Bangladesh)\n- BY (Belarus)\n- BE (Belgium)\n- BO (Bolivia)\n- BR (Brazil)\n- BG (Bulgaria)\n- CA (Canada)\n- CL (Chile)\n- CO (Colombia)\n- CR (Costa Rica)\n- CZ (Czech Republic)\n- DK (Denmark)\n- DO (Dominican Republic)\n- EC (Ecuador)\n- EG (Egypt)\n- SV (El Salvador)\n- EE (Estonia)\n- FI (Finland)\n- FR (France)\n- DE (Germany)\n- GR (Greece)\n- GT (Guatemala)\n- HN (Honduras)\n- HK (Hong Kong)\n- HU (Hungary)\n- IN (India)\n- ID (Indonesia)\n- IE (Ireland)\n- IL (Israel)\n- IT (Italy)\n- JP (Japan)\n- KZ (Kazakstan)\n- KE (Kenya)\n- MY (Malaysia)\n- MX (Mexico)\n- MA (Morocco)\n- MM (Myanmar)\n- NL (Netherlands)\n- NI (Nicaragua)\n- NG (Nigeria)\n- NO (Norway)\n- PK (Pakistan)\n- PA (Panama)\n- PY (Paraguay)\n- PE (Peru)\n- PH (Philippines)\n- PL (Poland)\n- PT (Portugal)\n- RO (Romania)\n- RU (Russia)\n- SA (Saudi Arabia)\n- SG (Singapore)\n- SK (Slovakia)\n- ZA (South Africa)\n- KR (South Korea)\n- ES (Spain)\n- SE (Sweden)\n- CH (Switzerland)\n- TW (Taiwan)\n- TH (Thailand)\n- TR (Turkey)\n- UA (Ukraine)\n- AE (United Arab Emirates)\n- UK (United Kingdom)\n- US (United States)\n- UY (Uruguay)\n- VE (Venezuela)\n- VN (Vietnam)","schema":{"type":"string","enum":["DZ","AR","AU","AT","BD","BY","BE","BO","BR","BG","CA","CL","CO","CR","CZ","DK","DO","EC","EG","SV","EE","FI","FR","DE","GR","GT","HN","HK","HU","IN","ID","IE","IL","IT","JP","KZ","KE","MY","MX","MA","MM","NL","NI","NG","NO","PK","PA","PY","PE","PH","PL","PT","RO","RU","SA","SG","SK","ZA","KR","ES","SE","CH","TW","TH","TR","UA","AE","UK","US","UY","VE","VN"],"examples":["DZ"]},"example":"DZ"},{"name":"page","in":"query","description":"Page number (starting from 1).","schema":{"type":"integer","default":1},"example":1},{"name":"page_size","in":"query","description":"Number of items per page (max 1000).","schema":{"type":"integer","default":50},"example":1000},{"name":"hashtags","in":"query","description":"Include the top N hashtags for each sound. Max: 10. Omit to exclude hashtags.","schema":{"type":"integer"},"example":3}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"items":[{"chart_index":1,"sound_id":7536694526191127327,"title":"Original sound","author":"creator","tokchart_score":951,"ugc_videos_total":259725,"ugc_videos_per_day":710,"ugc_videos_acceleration":120,"content_type":"original","sound_duration_seconds":18,"views_total":5000000,"likes_total":450000,"uploaded_at":"2026-06-01 12:34:56","trending_countries":["US","UK"],"trending_countries_ranked":[{"country":"US","rank":3},{"country":"UK","rank":12}],"spotify_url":"https:\/\/open.spotify.com\/track\/4iV5W9uYEdYUVa79Axb7Rh","matched_song":{"track_id":"018f77f0-3490-5c21-8f5f-a90548c5bd2f","spotify_uri":"spotify:track:4iV5W9uYEdYUVa79Axb7Rh","title":"Example Song","artists":[{"spotify_uri":"spotify:artist:06HL4z0CvFAxyc27GXpf02","name":"Example Artist","spotify_id":"06HL4z0CvFAxyc27GXpf02"},{"spotify_uri":null,"name":"Featured Artist","spotify_id":null}],"spotify_track_id":"4iV5W9uYEdYUVa79Axb7Rh","isrc":"USSM12600001","release_date":"2026-05-29","label":"Columbia","genres":["Pop"]},"cover_url":"https:\/\/assets.tokchart.com\/images\/sounds_data\/cover\/ab\/ab7f519e6d45a29a.webp","tiktok_url":"https:\/\/www.tiktok.com\/music\/-7536694526191127327","daily_stats":[{"date":"2026-06-04","videos_count":25810695},{"date":"2026-06-05","videos_count":25846806}],"hashtags":["dance","fyp","viral"]},{"chart_index":2,"sound_id":7536694526191127328,"title":"original sound - creator","author":"creator","tokchart_score":951,"ugc_videos_total":259725,"ugc_videos_per_day":710,"ugc_videos_acceleration":120,"content_type":"original","is_catalog":false,"sound_duration_seconds":18,"views_total":5000000,"likes_total":450000,"uploaded_at":"2026-06-01 12:34:56","trending_countries":["US"],"trending_countries_ranked":[{"country":"US","rank":41}],"spotify_url":null,"matched_song":null,"cover_url":null,"tiktok_url":"https:\/\/www.tiktok.com\/music\/-7536694526191127328","daily_stats":[{"date":"2026-06-03","videos_count":258315},{"date":"2026-06-05","videos_count":259725}],"hashtags":["fyp"]}],"total_items":1000,"page":1,"page_size":1000,"total_pages":1}],"properties":{"items":{"type":"array","prefixItems":[{"type":"object","properties":{"chart_index":{"type":"integer","const":1},"sound_id":{"type":"integer","const":7536694526191127327},"title":{"type":"string","const":"Original sound"},"author":{"type":"string","const":"creator"},"tokchart_score":{"type":"integer","const":987},"ugc_videos_total":{"type":"integer","const":25846806},"ugc_videos_per_day":{"type":"integer","const":36111},"ugc_videos_acceleration":{"type":"integer","const":1200},"content_type":{"type":"string","const":"music"},"is_catalog":{"type":"boolean"},"sound_duration_seconds":{"type":"integer","const":31},"views_total":{"type":"integer","const":500000000},"likes_total":{"type":"integer","const":45000000},"uploaded_at":{"type":"string","const":"2026-06-01 12:34:56"},"trending_countries":{"type":"array","prefixItems":[{"type":"string","const":"US"},{"type":"string","const":"UK"}],"minItems":2,"maxItems":2,"additionalItems":false},"trending_countries_ranked":{"type":"array","prefixItems":[{"type":"object","properties":{"country":{"type":"string","const":"US"},"rank":{"type":"integer","const":3}},"required":["country","rank"]},{"type":"object","properties":{"country":{"type":"string","const":"UK"},"rank":{"type":"integer","const":12}},"required":["country","rank"]}],"minItems":2,"maxItems":2,"additionalItems":false},"spotify_url":{"type":"string"},"matched_song":{"type":"object","properties":{"track_id":{"type":"string","const":"018f77f0-3490-5c21-8f5f-a90548c5bd2f"},"spotify_uri":{"type":"string","const":"spotify:track:4iV5W9uYEdYUVa79Axb7Rh"},"title":{"type":"string","const":"Example Song"},"artists":{"type":"array","prefixItems":[{"type":"object","properties":{"spotify_uri":{"type":"string","const":"spotify:artist:06HL4z0CvFAxyc27GXpf02"},"name":{"type":"string","const":"Example Artist"},"spotify_id":{"type":"string","const":"06HL4z0CvFAxyc27GXpf02"}},"required":["spotify_uri","name","spotify_id"]},{"type":"object","properties":{"spotify_uri":{"type":"null"},"name":{"type":"string","const":"Featured Artist"},"spotify_id":{"type":"null"}},"required":["spotify_uri","name","spotify_id"]}],"minItems":2,"maxItems":2,"additionalItems":false},"spotify_track_id":{"type":"string","const":"4iV5W9uYEdYUVa79Axb7Rh"},"isrc":{"type":"string","const":"USSM12600001"},"release_date":{"type":"string","const":"2026-05-29"},"label":{"type":"string","const":"Columbia"},"genres":{"type":"array","prefixItems":[{"type":"string","const":"Pop"}],"minItems":1,"maxItems":1,"additionalItems":false}},"required":["track_id","spotify_uri","title","artists","spotify_track_id","isrc","release_date","label","genres"]},"cover_url":{"type":"string","const":"https:\/\/assets.tokchart.com\/images\/sounds_data\/cover\/ab\/ab7f519e6d45a29a.webp"},"tiktok_url":{"type":"string","const":"https:\/\/www.tiktok.com\/music\/-7536694526191127327"},"daily_stats":{"type":"array","prefixItems":[{"type":"object","properties":{"date":{"type":"string","const":"2026-06-04"},"videos_count":{"type":"integer","const":25810695}},"required":["date","videos_count"]},{"type":"object","properties":{"date":{"type":"string","const":"2026-06-05"},"videos_count":{"type":"integer","const":25846806}},"required":["date","videos_count"]}],"minItems":2,"maxItems":2,"additionalItems":false},"hashtags":{"type":"array","prefixItems":[{"type":"string","const":"dance"},{"type":"string","const":"fyp"},{"type":"string","const":"viral"}],"minItems":3,"maxItems":3,"additionalItems":false}},"required":["chart_index","sound_id","title","author","tokchart_score","ugc_videos_total","ugc_videos_per_day","ugc_videos_acceleration","content_type","is_catalog","sound_duration_seconds","views_total","likes_total","uploaded_at","trending_countries","trending_countries_ranked","spotify_url","matched_song","cover_url","tiktok_url","daily_stats","hashtags"]},{"type":"object","properties":{"chart_index":{"type":"integer","const":2},"sound_id":{"type":"integer","const":7536694526191127328},"title":{"type":"string","const":"original sound - creator"},"author":{"type":"string","const":"creator"},"tokchart_score":{"type":"integer","const":951},"ugc_videos_total":{"type":"integer","const":259725},"ugc_videos_per_day":{"type":"integer","const":710},"ugc_videos_acceleration":{"type":"integer","const":120},"content_type":{"type":"string","const":"original"},"is_catalog":{"type":"boolean"},"sound_duration_seconds":{"type":"integer","const":18},"views_total":{"type":"integer","const":5000000},"likes_total":{"type":"integer","const":450000},"uploaded_at":{"type":"string","const":"2026-06-01 12:34:56"},"trending_countries":{"type":"array","prefixItems":[{"type":"string","const":"US"}],"minItems":1,"maxItems":1,"additionalItems":false},"trending_countries_ranked":{"type":"array","prefixItems":[{"type":"object","properties":{"country":{"type":"string","const":"US"},"rank":{"type":"integer","const":41}},"required":["country","rank"]}],"minItems":1,"maxItems":1,"additionalItems":false},"spotify_url":{"type":"null"},"matched_song":{"type":"null"},"cover_url":{"type":"null"},"tiktok_url":{"type":"string","const":"https:\/\/www.tiktok.com\/music\/-7536694526191127328"},"daily_stats":{"type":"array","prefixItems":[{"type":"object","properties":{"date":{"type":"string","const":"2026-06-03"},"videos_count":{"type":"integer","const":258315}},"required":["date","videos_count"]},{"type":"object","properties":{"date":{"type":"string","const":"2026-06-05"},"videos_count":{"type":"integer","const":259725}},"required":["date","videos_count"]}],"minItems":2,"maxItems":2,"additionalItems":false},"hashtags":{"type":"array","prefixItems":[{"type":"string","const":"fyp"}],"minItems":1,"maxItems":1,"additionalItems":false}},"required":["chart_index","sound_id","title","author","tokchart_score","ugc_videos_total","ugc_videos_per_day","ugc_videos_acceleration","content_type","is_catalog","sound_duration_seconds","views_total","likes_total","uploaded_at","trending_countries","trending_countries_ranked","spotify_url","matched_song","cover_url","tiktok_url","daily_stats","hashtags"]}],"minItems":2,"maxItems":2,"additionalItems":false},"total_items":{"type":"integer","const":1000},"page":{"type":"integer","const":1},"page_size":{"type":"integer","const":1000},"total_pages":{"type":"integer","const":1}},"required":["items","total_items","page","page_size","total_pages"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"x-response-fields":[{"name":"ugc_videos_total","description":"Total videos using the sound."},{"name":"ugc_videos_per_day","description":"New videos using the sound per day."},{"name":"ugc_videos_acceleration","description":"How fast `ugc_videos_per_day` is changing."},{"name":"content_type","description":"`music` when the sound is matched to a song, `original` when it isn't."},{"name":"is_catalog","description":"True for Catalog sounds, false for UGC sounds. False with `content_type` `music` is UGC that contains music."},{"name":"trending_countries","description":"The countries where the sound is trending, strongest first."},{"name":"trending_countries_ranked","description":"The same countries, with the sound's chart position in each."},{"name":"spotify_url","description":"A Spotify track link, or null when there is none."},{"name":"matched_song","description":"The song linked to the sound, or null when it has none."},{"name":"matched_song.track_id","description":"Works with `\/tiktok\/audio\/tracks\/{track_id}\/sounds`."},{"name":"matched_song.artists[].spotify_id","description":"The artist's Spotify ID, or null when it's unknown or the name is shared by more than one Spotify artist."},{"name":"matched_song.spotify_track_id","description":"The ID in `spotify_url`. A sound can have a `spotify_url` and a null `matched_song`."},{"name":"matched_song.isrc","description":"Null when unknown."},{"name":"matched_song.release_date","description":"`YYYY-MM-DD`, or null when unknown."},{"name":"matched_song.label","description":"Null when unknown."},{"name":"cover_url","description":"The sound's cover image, or null when there is none. For display and attribution only."},{"name":"tiktok_url","description":"The sound's TikTok page. For display and attribution only."},{"name":"daily_stats","description":"The sound's total videos over the last 14 days, oldest first. Only days we have a figure are included, so dates can have gaps and the list can be empty."},{"name":"hashtags","description":"The top hashtags used with the sound. Only returned when you pass the `hashtags` parameter."}]}},"\/tiktok\/audio\/matches":{"get":{"operationId":"customerApi.spotifyAudioMatches","description":"Requires the **Read trending TikTok sounds worldwide and Spotify matches** permission.\n\nCountry shares and aggregate engagement metrics are calculated from the\nvideos observed by Tokchart. They are not guaranteed platform-wide totals.\nEach sound includes at most its top 20 observed countries.","summary":"Get TikTok sounds matched to a Spotify track","tags":["TikTok Audio Trending"],"parameters":[{"name":"spotify_url","in":"query","required":true,"description":"A Spotify track HTTPS URL (including \/intl-xx\/ links and query parameters) or spotify:track URI. Artist, album, playlist and shortened spotify.link URLs are not supported.","schema":{"type":"string"},"example":"https:\/\/open.spotify.com\/track\/4iV5W9uYEdYUVa79Axb7Rh"}],"responses":{"202":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"spotify_identity_pending","message":"Tokchart is resolving this Spotify track. Retry shortly."}],"properties":{"error":{"type":"string","const":"spotify_identity_pending"},"message":{"type":"string","const":"Tokchart is resolving this Spotify track. Retry shortly."}},"required":["error","message"]}}},"headers":{"Retry-After":{"schema":{"type":"string","const":"30"}}}},"503":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"spotify_lookup_temporarily_unavailable","message":"The Spotify match lookup is temporarily unavailable."}],"properties":{"error":{"type":"string","const":"spotify_lookup_temporarily_unavailable"},"message":{"type":"string","const":"The Spotify match lookup is temporarily unavailable."}},"required":["error","message"]}}},"headers":{"Retry-After":{"schema":{"type":"string","const":"30"}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"spotify_track_not_found","message":"Tokchart has no TikTok sounds matched to this Spotify track."}],"properties":{"error":{"type":"string","const":"spotify_track_not_found"},"message":{"type":"string","const":"Tokchart has no TikTok sounds matched to this Spotify track."}},"required":["error","message"]}}}},"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":{"recording":{"spotify_id":"4iV5W9uYEdYUVa79Axb7Rh","title":"Example track","artists":["Example artist"],"isrc":"USRC17607839"},"sounds":[{"tiktok_sound_id":"7662052657323182081","title":"Example track","author":"Example artist","ugc_video_count":128800,"metrics":{"views":421000000,"likes":38000000,"comments":240000,"sampled_videos":1250},"country_breakdown":[{"country_code":"US","sampled_videos":480,"sample_share_percent":38.4}],"stats_as_of":"2026-08-31 07:30:00"}]},"meta":{"coverage":"known_matches","metrics_basis":"observed_videos"}}],"properties":{"data":{"type":["array","null"],"items":{}},"meta":{"type":"object","properties":{"coverage":{"type":"string","const":"known_matches"},"metrics_basis":{"type":"string","const":"observed_videos"}},"required":["coverage","metrics_basis"]}},"required":["data","meta"]}}}},"422":{"description":"Validation error","content":{"application\/json":{"schema":{"type":"object","examples":[{"message":"The Spotify URL must identify a Spotify track.","errors":{"spotify_url":["The Spotify URL must identify a Spotify track."]}}],"properties":{"message":{"type":"string","description":"Errors overview."},"errors":{"type":"object","description":"A detailed description of each field that failed validation.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["message","errors"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/creators":{"get":{"operationId":"tikTokCreators.index","description":"Requires the TikTok Creators permission.\n\nResults are ordered by the latest captured follower count. Each result\nincludes up to 10 of the creator's matching videos, newest first.","summary":"Get creators by country and music genre","tags":["TikTok Creators"],"parameters":[{"name":"country","in":"query","required":true,"description":"Required ISO 3166-1 alpha-2 country code, in any case. GB and UK both mean the United Kingdom. Supported values: DZ (Algeria), AR (Argentina), AT (Austria), BE (Belgium), BR (Brazil), CA (Canada), CL (Chile), CO (Colombia), EC (Ecuador), EG (Egypt), FR (France), DE (Germany), GR (Greece), ID (Indonesia), IE (Ireland), IT (Italy), JP (Japan), KZ (Kazakhstan), KE (Kenya), MY (Malaysia), MX (Mexico), MA (Morocco), MM (Myanmar), NL (Netherlands), NG (Nigeria), PK (Pakistan), PA (Panama), PE (Peru), PH (Philippines), PL (Poland), PT (Portugal), RO (Romania), SA (Saudi Arabia), ZA (South Africa), ES (Spain), SE (Sweden), CH (Switzerland), TH (Thailand), TR (Turkey), UA (Ukraine), AE (United Arab Emirates), UK (United Kingdom), US (United States), VN (Vietnam).","schema":{"type":"string","enum":["DZ","AR","AT","BE","BR","CA","CL","CO","EC","EG","FR","DE","GR","ID","IE","IT","JP","KZ","KE","MY","MX","MA","MM","NL","NG","PK","PA","PE","PH","PL","PT","RO","SA","ZA","ES","SE","CH","TH","TR","UA","AE","GB","UK","US","VN"]},"example":"US"},{"name":"genre","in":"query","required":true,"description":"Required canonical lower-case genre key. Supported values: blues (Blues), brazilian-funk (Brazilian Funk), childrens (Children's Music), classical (Classical), comedy (Comedy), corridos (Corridos), country (Country), electronic (Electronic), folk (Folk), hip-hop-rap (Hip-Hop\/Rap), holiday (Holiday), jazz (Jazz), latin (Latin), latin-pop (Latin Pop), latin-urban (Latin Urban), other (Other), pop (Pop), r-and-b (R&B), reggae (Reggae), reggaeton (Reggaeton), regional-mexican (Regional Mexican), religious (Religious), rock (Rock), soundtrack (Soundtrack), world (World).","schema":{"type":"string","enum":["blues","brazilian-funk","childrens","classical","comedy","corridos","country","electronic","folk","hip-hop-rap","holiday","jazz","latin","latin-pop","latin-urban","other","pop","r-and-b","reggae","reggaeton","regional-mexican","religious","rock","soundtrack","world"]},"example":"hip-hop-rap"},{"name":"days","in":"query","description":"Recent video window in days (1-90).","schema":{"type":"integer","default":30},"example":30},{"name":"sort","in":"query","description":"Result order. Currently only followers is supported.","schema":{"type":"string","default":"followers"},"example":"followers"},{"name":"limit","in":"query","description":"Maximum creators to return (1-100).","schema":{"type":"integer","default":100},"example":100}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"country":"US","genre_key":"hip-hop-rap","genre":"Hip-Hop\/Rap","days":30,"sort":"followers","limit":100,"items":[{"account_id":123456789,"username":"creator","name":"Creator Name","bio":"Music creator","profile_url":"https:\/\/www.tiktok.com\/@creator","followers_count":250000,"followers_captured_at":"2026-08-24T08:30:00Z","matching_posts_count":3,"latest_matching_post_at":"2026-08-23T12:00:00Z","posts":[{"video_id":987654321,"url":"https:\/\/www.tiktok.com\/@creator\/video\/987654321","description":"New track","uploaded_at":"2026-08-23T12:00:00Z","sound":{"sound_id":456789,"title":"Track","artist":"Artist One, Artist Two","genre_key":"hip-hop-rap"}}]}]}],"properties":{"country":{"type":"string","const":"US"},"genre_key":{"type":"string","const":"hip-hop-rap"},"genre":{"type":"string","const":"Hip-Hop\/Rap"},"days":{"type":"integer","const":30},"sort":{"type":"string","const":"followers"},"limit":{"type":"integer","const":100},"items":{"type":"array","prefixItems":[{"type":"object","properties":{"account_id":{"type":"integer","const":123456789},"username":{"type":"string","const":"creator"},"name":{"type":"string","const":"Creator Name"},"bio":{"type":"string","const":"Music creator"},"profile_url":{"type":"string","const":"https:\/\/www.tiktok.com\/@creator"},"followers_count":{"type":"integer","const":250000},"followers_captured_at":{"type":"string","const":"2026-08-24T08:30:00Z"},"matching_posts_count":{"type":"integer","const":3},"latest_matching_post_at":{"type":"string","const":"2026-08-23T12:00:00Z"},"posts":{"type":"array","prefixItems":[{"type":"object","properties":{"video_id":{"type":"integer","const":987654321},"url":{"type":"string","const":"https:\/\/www.tiktok.com\/@creator\/video\/987654321"},"description":{"type":"string","const":"New track"},"uploaded_at":{"type":"string","const":"2026-08-23T12:00:00Z"},"sound":{"type":"object","properties":{"sound_id":{"type":"integer","const":456789},"title":{"type":"string","const":"Track"},"artist":{"type":"string","const":"Artist One, Artist Two"},"genre_key":{"type":"string","const":"hip-hop-rap"}},"required":["sound_id","title","artist","genre_key"]}},"required":["video_id","url","description","uploaded_at","sound"]}],"minItems":1,"maxItems":1,"additionalItems":false}},"required":["account_id","username","name","bio","profile_url","followers_count","followers_captured_at","matching_posts_count","latest_matching_post_at","posts"]}],"minItems":1,"maxItems":1,"additionalItems":false}},"required":["country","genre_key","genre","days","sort","limit","items"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/creators\/search":{"get":{"operationId":"tikTokCreators.search","description":"Requires the TikTok Creators permission. Give a hashtag, a topic or both; with both, a creator must match both.\n\nA hashtag finds creators who used it recently, with the ones who use it most, and mostly, first. A topic finds\ncreators whose content is tagged with it, such as skincare or marathon training, then creators using it as a\nhashtag. topics, category and language are empty for creators we haven't tagged yet. matched_by says why each\ncreator is listed. Each result includes up to 5 of the creator's posts, those using the hashtag first.","summary":"Search creators by hashtag or topic","tags":["TikTok Creators"],"parameters":[{"name":"hashtag","in":"query","description":"One hashtag, with or without the #, in any case. Required unless topic is given.","schema":{"type":"string"},"example":"skincare"},{"name":"topic","in":"query","description":"A topic of one or more words, in any case. Required unless hashtag is given.","schema":{"type":"string"},"example":"marathon training"},{"name":"category","in":"query","description":"Only creators in this content category, written exactly as in the category field of a result, such as Beauty & Personal Care. Leaves out creators with no category yet.","schema":{"type":"string"},"example":"Beauty & Personal Care"},{"name":"country","in":"query","description":"Only creators in this country: an ISO 3166-1 alpha-2 code, in any case. GB and UK both mean the United Kingdom.","schema":{"type":"string"},"example":"US"},{"name":"language","in":"query","description":"Only creators whose content is in this language: an ISO 639-1 code. Leaves out creators with no language yet.","schema":{"type":"string"},"example":"es"},{"name":"min_followers","in":"query","description":"Fewest followers.","schema":{"type":"integer"},"example":10000},{"name":"max_followers","in":"query","description":"Most followers.","schema":{"type":"integer"},"example":1000000},{"name":"min_views","in":"query","description":"Lowest median views per video.","schema":{"type":"integer"},"example":50000},{"name":"days","in":"query","description":"How recently a hashtag must have been used, in days (1-180).","schema":{"type":"integer","default":180},"example":90},{"name":"sort","in":"query","description":"Result order: relevance, followers or views.","schema":{"type":"string","enum":["relevance","followers","views"],"default":"relevance"},"example":"relevance"},{"name":"page","in":"query","description":"Page of results (1-100). has_more says whether there is another.","schema":{"type":"integer","default":1},"example":1},{"name":"limit","in":"query","description":"Maximum creators per page (1-100).","schema":{"type":"integer","default":50},"example":50}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"hashtag":"skincare","sort":"relevance","page":1,"limit":50,"has_more":true,"items":[{"account_id":123456789,"username":"creator","name":"Creator Name","bio":"Skincare routines for sensitive skin","profile_url":"https:\/\/www.tiktok.com\/@creator","followers_count":250000,"median_views":48000,"engagement_rate":0.062,"country":"US","language":"en","category":"Beauty & Personal Care","topics":["korean skincare","sensitive skin care"],"matched_by":["hashtag"],"matching_posts_count":24,"share_of_posts":0.6,"latest_matching_post_at":"2026-08-23T12:00:00Z","posts":[{"video_id":987654321,"url":"https:\/\/www.tiktok.com\/@creator\/video\/987654321","description":"My morning routine #skincare","uploaded_at":"2026-08-23T12:00:00Z"}]}]}],"properties":{"hashtag":{"type":"string","const":"skincare"},"sort":{"type":"string","const":"relevance"},"page":{"type":"integer","const":1},"limit":{"type":"integer","const":50},"has_more":{"type":"boolean"},"items":{"type":"array","prefixItems":[{"type":"object","properties":{"account_id":{"type":"integer","const":123456789},"username":{"type":"string","const":"creator"},"name":{"type":"string","const":"Creator Name"},"bio":{"type":"string","const":"Skincare routines for sensitive skin"},"profile_url":{"type":"string","const":"https:\/\/www.tiktok.com\/@creator"},"followers_count":{"type":"integer","const":250000},"median_views":{"type":"integer","const":48000},"engagement_rate":{"type":"number"},"country":{"type":"string","const":"US"},"language":{"type":"string","const":"en"},"category":{"type":"string","const":"Beauty & Personal Care"},"topics":{"type":"array","prefixItems":[{"type":"string","const":"korean skincare"},{"type":"string","const":"sensitive skin care"}],"minItems":2,"maxItems":2,"additionalItems":false},"matched_by":{"type":"array","prefixItems":[{"type":"string","const":"hashtag"}],"minItems":1,"maxItems":1,"additionalItems":false},"matching_posts_count":{"type":"integer","const":24},"share_of_posts":{"type":"number"},"latest_matching_post_at":{"type":"string","const":"2026-08-23T12:00:00Z"},"posts":{"type":"array","prefixItems":[{"type":"object","properties":{"video_id":{"type":"integer","const":987654321},"url":{"type":"string","const":"https:\/\/www.tiktok.com\/@creator\/video\/987654321"},"description":{"type":"string","const":"My morning routine #skincare"},"uploaded_at":{"type":"string","const":"2026-08-23T12:00:00Z"}},"required":["video_id","url","description","uploaded_at"]}],"minItems":1,"maxItems":1,"additionalItems":false}},"required":["account_id","username","name","bio","profile_url","followers_count","median_views","engagement_rate","country","language","category","topics","matched_by","matching_posts_count","share_of_posts","latest_matching_post_at","posts"]}],"minItems":1,"maxItems":1,"additionalItems":false}},"required":["hashtag","sort","page","limit","has_more","items"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-artists":{"get":{"operationId":"trackedArtists.index","description":"Requires the **Track artists and read their TikTok sounds** permission.\n\n`status` is `active` once the artist has songs to show, `pending` while\nTokchart reads the Spotify catalogue of an artist it did not know yet\n(usually a few minutes), and `not_found` when Spotify has no such artist.\n\n`refresh.status` is `warming_up` for about 27 hours after an artist is\ntracked, while their sounds complete a first refresh cycle, then `active`;\nit is `not_started` while the artist is pending. `refresh.refreshed_sounds`\nis how many of the artist's sounds are refreshed daily. Every sound also\ncarries its own `updated_at`.","summary":"List tracked artists","tags":["Tracked Artists"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":[{"spotify_id":"790FomKkXshlbRYZFtlgla","spotify_uri":"spotify:artist:790FomKkXshlbRYZFtlgla","name":"Example artist","status":"active","tracked_since":"2026-09-28T10:00:00Z","refresh":{"status":"active","refreshed_sounds":2310,"synced_at":"2026-09-29T02:30:00Z"}},{"spotify_id":"12fRkVfO2fUsz1QHgDAG3g","spotify_uri":"spotify:artist:12fRkVfO2fUsz1QHgDAG3g","name":null,"status":"pending","tracked_since":"2026-10-10T09:00:00Z","refresh":{"status":"not_started","refreshed_sounds":null,"synced_at":null}}],"meta":{"limit":10,"used":2}}],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"spotify_id":{"type":"string"},"spotify_uri":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":"string"},"tracked_since":{"type":"string"},"refresh":{"type":"object","properties":{"status":{"type":"string","enum":["warming_up","active","not_started"]},"refreshed_sounds":{"type":["integer","null"]},"synced_at":{"type":["string","null"]}},"required":["status","refreshed_sounds","synced_at"]}},"required":["spotify_id","spotify_uri","name","status","tracked_since","refresh"]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer","minimum":0}},"required":["limit","used"]}},"required":["data","meta"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"post":{"operationId":"trackedArtists.store","description":"Requires the **Track artists and read their TikTok sounds** permission.\n\nStarts refreshing the artist's sounds. Tracking an artist you already track\nreturns it unchanged with status 200. Each account can track a limited\nnumber of artists; contact us to raise it.\n\nAn artist Tokchart does not know yet returns 202 with `status: pending`.\nThey are tracked and count toward your allowance; Tokchart reads their\nSpotify catalogue and the artist becomes `active`, usually within minutes.\nPoll the list or the artist's tracks; `Retry-After` suggests when.\n\n404 `spotify_artist_not_found` means Spotify has no artist with this ID.\n503 `spotify_lookup_temporarily_unavailable` means the catalogue read could\nnot start right now; the artist was not added, so retry after `Retry-After`.","summary":"Track an artist","tags":["Tracked Artists"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"spotify_artist":{"type":"string","description":"A Spotify artist HTTPS URL (including \/intl-xx\/ links and query parameters), spotify:artist URI or 22-character artist ID.","examples":["https:\/\/open.spotify.com\/artist\/790FomKkXshlbRYZFtlgla"]}},"required":["spotify_artist"]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"string"}}}},"202":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":{"spotify_id":"12fRkVfO2fUsz1QHgDAG3g","spotify_uri":"spotify:artist:12fRkVfO2fUsz1QHgDAG3g","name":null,"status":"pending","tracked_since":"2026-10-10T09:00:00Z","refresh":{"status":"not_started","refreshed_sounds":null,"synced_at":null}}}],"properties":{"data":{"type":"object","properties":{"spotify_id":{"type":"string"},"spotify_uri":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":"string"},"tracked_since":{"type":"string"},"refresh":{"type":"object","properties":{"status":{"type":"string","enum":["warming_up","active","not_started"]},"refreshed_sounds":{"type":["integer","null"]},"synced_at":{"type":["string","null"]}},"required":["status","refreshed_sounds","synced_at"]}},"required":["spotify_id","spotify_uri","name","status","tracked_since","refresh"]}},"required":["data"]}}},"headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"spotify_lookup_temporarily_unavailable","message":"Tokchart could not look this Spotify artist up right now. Retry shortly."}],"properties":{"error":{"type":"string","const":"spotify_lookup_temporarily_unavailable"},"message":{"type":"string","const":"Tokchart could not look this Spotify artist up right now. Retry shortly."}},"required":["error","message"]}}},"headers":{"Retry-After":{"schema":{"type":"string","const":"30"}}}},"409":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"tracked_artist_limit_reached","message":"You can track up to 10 artists."}],"properties":{"error":{"type":"string","const":"tracked_artist_limit_reached"},"message":{"type":"string"}},"required":["error","message"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"spotify_artist_not_found","message":"Spotify has no artist with this ID."}],"properties":{"error":{"type":"string","const":"spotify_artist_not_found"},"message":{"type":"string"}},"required":["error","message"]}}}},"422":{"description":"Validation error","content":{"application\/json":{"schema":{"type":"object","examples":[{"message":"The Spotify artist must be a Spotify artist link, URI or ID.","errors":{"spotify_artist":["The Spotify artist must be a Spotify artist link, URI or ID."]}}],"properties":{"message":{"type":"string","description":"Errors overview."},"errors":{"type":"object","description":"A detailed description of each field that failed validation.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["message","errors"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"201":{"description":"","content":{"application\/json":{"schema":{"type":"string","examples":[{"data":{"spotify_id":"790FomKkXshlbRYZFtlgla","spotify_uri":"spotify:artist:790FomKkXshlbRYZFtlgla","name":"Example artist","status":"active","tracked_since":"2026-09-28T10:00:00Z","refresh":{"status":"active","refreshed_sounds":2310,"synced_at":"2026-09-29T02:30:00Z"}}}]}}}}}}},"\/tiktok\/audio\/tracked-artists\/{spotifyArtistId}":{"delete":{"operationId":"trackedArtists.destroy","description":"Requires the **Track artists and read their TikTok sounds** permission.","summary":"Stop tracking an artist","tags":["Tracked Artists"],"parameters":[{"name":"spotifyArtistId","in":"path","required":true,"description":"The 22-character Spotify artist ID of a tracked artist.","schema":{"type":"string"},"example":"790FomKkXshlbRYZFtlgla"}],"responses":{"204":{"description":"No content","content":{"application\/json":{"schema":{"type":"string"}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"artist_not_tracked","message":"You are not tracking this artist."}],"properties":{"error":{"type":"string","const":"artist_not_tracked"},"message":{"type":"string","const":"You are not tracking this artist."}},"required":["error","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-artists\/{spotifyArtistId}\/tracks":{"get":{"operationId":"trackedArtists.tracks","description":"Requires the **Track artists and read their TikTok sounds** permission.\n\nThe artist's songs, ordered by total TikTok videos, without their sounds.\nRead each track's sounds from `GET \/tiktok\/audio\/tracks\/{track_id}\/sounds`.\nFollow `next_cursor` until it is null to read every track.\n\nSongs from the artist's Spotify catalogue that have no TikTok sounds yet\nare included with `track_id: null`, `sounds_count: 0` and\n`ugc_videos_total: 0`; they get a `track_id` once a TikTok sound uses\nthem. A `pending` artist has no tracks yet.\n\n`match_source` says why a track is listed under the artist: `listing` (its\nSpotify listing names them), `catalogue` (it is on their Spotify profile) or\n`name` (it has no Spotify listing yet, and only they use this name).","summary":"List a tracked artist's tracks","tags":["Tracked Artists"],"parameters":[{"name":"spotifyArtistId","in":"path","required":true,"description":"The 22-character Spotify artist ID of a tracked artist.","schema":{"type":"string"},"example":"790FomKkXshlbRYZFtlgla"},{"name":"cursor","in":"query","description":"The `next_cursor` value from the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of tracks per page, from 1 to 500.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":["array","null"],"examples":[{"artist":{"spotify_uri":"spotify:artist:790FomKkXshlbRYZFtlgla","name":"Example artist","spotify_id":"790FomKkXshlbRYZFtlgla","tracked_since":"2026-09-28T10:00:00Z","refresh":{"status":"active","refreshed_sounds":2310,"synced_at":"2026-09-29T02:30:00Z"}},"tracks":[{"track_id":"1fed0d6b-55bf-5e9e-b0b1-c765d3270258","spotify_uri":"spotify:track:0DWdj2oZMBFSzRsi2Cvfzf","title":"Example track","artists":[{"spotify_uri":"spotify:artist:790FomKkXshlbRYZFtlgla","name":"Example artist","spotify_id":"790FomKkXshlbRYZFtlgla"}],"spotify_track_id":"0DWdj2oZMBFSzRsi2Cvfzf","isrc":"USRC17607839","release_date":"2023-02-24","label":"Example label","sounds_count":259,"ugc_videos_total":6370062,"match_source":"listing"}],"next_cursor":"eyJvIjoxMDB9","meta":{"total_tracks":163}}],"items":{}}}}},"404":{"description":"The artist was resolvable when tracked; keep answering with the\ntracking state rather than a misleading empty catalog.","content":{"application\/json":{"schema":{"examples":[{"error":"artist_not_tracked","message":"You are not tracking this artist."}],"anyOf":[{"type":"object","properties":{"error":{"type":"string","const":"spotify_artist_not_found"},"message":{"type":"string","const":"Tokchart has no artist linked to this Spotify artist."}},"required":["error","message"]},{"type":"object","properties":{"error":{"type":"string","const":"artist_not_tracked"},"message":{"type":"string","const":"You are not tracking this artist."}},"required":["error","message"]}]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracks\/{trackId}\/sounds":{"get":{"operationId":"customerApi.trackSounds","description":"Requires the **Track artists and read their TikTok sounds** or **Track songs and read their TikTok sounds** permission.\n\nThe track includes `ugc_videos_per_day`: the last 30 completed UTC days of net new videos across all matched audios, as {date, count}. Missing baselines return null, and corrections can be negative. Counts are carried forward between captures. An empty matched sound set returns an empty series.\n\nSounds are ordered by video count. Follow `next_cursor` until it is null to\nread every sound: the pages add up to `meta.total_sounds`. Sounds TikTok has\nsince removed are included with `is_removed: true` and their last observed\nstats.\n\n`ugc_videos_total` is the number of TikTok videos using the sound, and\n`updated_at` is when Tokchart last read that count. Views, likes, comments,\nshares and `engagement_rate` ((likes + comments + shares + saves) \/ views)\nare summed from the videos Tokchart has observed for the sound and\nrecalculated daily; `metrics_updated_at` is when the newest of those video\nstats was captured. They are not guaranteed platform-wide totals, and are\nnull until Tokchart has observed videos for the sound.","summary":"Get a track's TikTok sounds","tags":["Tracked Artists"],"parameters":[{"name":"trackId","in":"path","required":true,"description":"The `track_id` from the tracked artist tracks list.","schema":{"type":"string"},"example":"1fed0d6b-55bf-5e9e-b0b1-c765d3270258"},{"name":"cursor","in":"query","description":"The `next_cursor` value from the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of sounds per page, from 1 to 250.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":["object","null"],"examples":[{"track":{"track_id":"1fed0d6b-55bf-5e9e-b0b1-c765d3270258","spotify_uri":"spotify:track:0DWdj2oZMBFSzRsi2Cvfzf","title":"Example track","artists":[{"spotify_uri":"spotify:artist:790FomKkXshlbRYZFtlgla","name":"Example artist","spotify_id":"790FomKkXshlbRYZFtlgla"}],"spotify_track_id":"0DWdj2oZMBFSzRsi2Cvfzf","isrc":"USRC17607839","release_date":"2023-02-24","label":"Example label","sounds_count":259,"ugc_videos_total":6370062,"ugc_videos_per_day":[{"date":"2026-10-01","count":12500},{"date":"2026-10-02","count":null}]},"sounds":[{"sound_id":"7200995956416841729","url":"https:\/\/www.tiktok.com\/music\/sound-7200995956416841729","title":"Example track","author":"Example artist","content_type":"music","is_catalog":true,"cover_url":"https:\/\/p16-sign.tiktokcdn-us.com\/example.jpeg","audio_url":"https:\/\/sf16-music.tiktokcdn-us.com\/example","uploaded_at":"2023-02-17T05:42:32Z","is_removed":false,"stats":{"ugc_videos_total":1823417,"views_total":4219455439,"likes_total":276015683,"comments_total":2258827,"shares_total":18740439,"engagement_rate":0.073605,"updated_at":"2026-09-27T16:37:24Z","metrics_updated_at":"2026-09-26T11:05:16Z"}}],"next_cursor":"eyJvIjoxMDB9","meta":{"total_sounds":259,"metrics_basis":"observed_videos"}}],"properties":{"track":{"type":"string","description":"The ID the client asked for, so the response matches its request."},"sounds":{"type":"array","items":{}},"next_cursor":{"type":["string","null"]},"meta":{"type":"object","properties":{"total_sounds":{"type":"integer"},"metrics_basis":{"type":"string","const":"observed_videos"}},"required":["total_sounds","metrics_basis"]}},"required":["track","sounds","next_cursor","meta"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"track_not_found","message":"Tokchart has no track with this ID."}],"properties":{"error":{"type":"string","const":"track_not_found"},"message":{"type":"string","const":"Tokchart has no track with this ID."}},"required":["error","message"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-songs":{"get":{"operationId":"trackedSongs.index","description":"Requires the **Track songs and read their TikTok sounds** permission. `id` is the song's Tokchart ID: use it to stop tracking the song, read its sounds or remove it from a list. It never changes. `track_id` is the identified recording, also accepted by \"Get a track's TikTok sounds\". Each song's `status` is `active` once Tokchart has identified it, `pending` while Tokchart looks it up, or `not_found` when the lookup found no recording. Unidentified songs have a null `track_id` and a `lookup` object with `checked_at` and `recheck_after` (when Tokchart asks again; null while pending). Active and pending songs count toward the account-wide `meta.used`; `not_found` songs remain saved for retries without using the allowance. They count again when pending or identified.\n\n`lists` holds the IDs of the song's lists, and `expires_at` is when a list removes it from your tracked songs (null: never). Pass `list_id` to list one list's songs.\n\nUnidentified tracked songs are looked up again daily during the first week after adding them, then weekly. `lookup.recheck_after` gives the next identity lookup deadline; the scheduled check runs every five minutes. Once identified, their sounds start refreshing daily.","summary":"List tracked songs","tags":["Tracked Songs"],"parameters":[{"name":"list_id","in":"query","description":"Only the songs in this list.","schema":{"type":"integer"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":[{"id":"0199c3a2-5f1e-7c3b-9a4d-2e8f6b1c7d90","spotify_track_id":"0DWdj2oZMBFSzRsi2Cvfzf","spotify_uri":"spotify:track:0DWdj2oZMBFSzRsi2Cvfzf","track_id":"1fed0d6b-55bf-5e9e-b0b1-c765d3270258","title":"Example song","status":"active","tracked_since":"2026-10-01T12:00:00Z","refresh":{"status":"warming_up","refreshed_sounds":102,"synced_at":"2026-10-01T12:00:05Z"},"artists_label":"Example artist","image_url":null,"lists":[],"expires_at":null,"lookup":null},{"id":"0199c3a2-6a40-7f12-8b5e-4c1d9e2a3f71","spotify_track_id":"4iV5W9uYEdYUVa79Axb7Rh","spotify_uri":"spotify:track:4iV5W9uYEdYUVa79Axb7Rh","track_id":null,"title":null,"status":"pending","tracked_since":"2026-10-02T09:00:00Z","refresh":{"status":"not_started","refreshed_sounds":null,"synced_at":null},"artists_label":"Example artist","image_url":null,"lists":[12],"expires_at":"2026-12-31T09:00:00Z","lookup":{"checked_at":"2026-10-02T09:00:00Z","recheck_after":null}}],"meta":{"limit":100,"used":2}}],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"spotify_track_id":{"type":"string"},"spotify_uri":{"type":"string"},"track_id":{"type":["string","null"]},"title":{"type":["string","null"]},"status":{"type":"string"},"tracked_since":{"type":"string"},"refresh":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","warming_up","active"]},"refreshed_sounds":{"type":["integer","null"]},"synced_at":{"type":["string","null"]}},"required":["status","refreshed_sounds","synced_at"]},"artists_label":{"type":["string","null"]},"image_url":{"type":["string","null"]},"lists":{"anyOf":[{"type":"array","items":{}},{"type":"object","additionalProperties":{}}]},"expires_at":{"type":["string","null"]},"lookup":{"type":["object","null"],"properties":{"checked_at":{"type":["string","null"]},"recheck_after":{"type":["string","null"]}},"required":["checked_at","recheck_after"]}},"required":["id","spotify_track_id","spotify_uri","track_id","title","status","tracked_since","refresh","artists_label","image_url","lists","expires_at","lookup"]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer","minimum":0}},"required":["limit","used"]}},"required":["data","meta"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"list_not_found"},"message":{"type":"string","const":"You have no list with this ID."}},"required":["error","message"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"post":{"operationId":"trackedSongs.store","description":"Requires the **Track songs and read their TikTok sounds** permission. Adding an existing song returns 200; a new song returns 201. A full tracking allowance returns 409.\n\nA song Tokchart has not identified yet returns 202 with `status: pending`. It is tracked and counts toward your allowance; Tokchart looks it up and the song becomes `active`, usually within minutes. Poll the list or the song's sounds; `Retry-After` suggests when.\n\n404 `spotify_track_not_found` means Tokchart already looked this song up and found no recording for it. 503 `spotify_lookup_temporarily_unavailable` means the lookup could not start right now; the song was not added, so retry after `Retry-After`.\n\nTo add many songs at once, send `spotify_tracks` (up to 500) instead of `spotify_track`, and optionally `list_id`. Every song is added, or none when they do not fit your allowance (409). Songs Tokchart does not know yet are added as `pending` and looked up in the background; check them with the list. The response is 201 when at least one song was added, otherwise 200, with `meta.added` and `meta.already_tracked`. Songs added into a list follow the list's `stop_after_days`; songs added without one are never ended by a list.","summary":"Track a song","tags":["Tracked Songs"],"requestBody":{"content":{"application\/json":{"schema":{"type":"object","properties":{"spotify_track":{"type":"string","description":"Spotify song link, URI or 22-character ID. Send this or spotify_tracks.","examples":["https:\/\/open.spotify.com\/track\/0DWdj2oZMBFSzRsi2Cvfzf"]},"spotify_tracks":{"type":"array","description":"Up to 500 Spotify song links, URIs or IDs, to add at once.","examples":[["0DWdj2oZMBFSzRsi2Cvfzf","spotify:track:4iV5W9uYEdYUVa79Axb7Rh"]],"items":{}},"list_id":{"type":"integer","description":"With spotify_tracks: a list of yours that the songs join.","examples":[12]}}}}}},"responses":{"202":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":{"id":"0199c3a2-6a40-7f12-8b5e-4c1d9e2a3f71","spotify_track_id":"4iV5W9uYEdYUVa79Axb7Rh","spotify_uri":"spotify:track:4iV5W9uYEdYUVa79Axb7Rh","track_id":null,"title":null,"status":"pending","tracked_since":"2026-10-02T09:00:00Z","refresh":{"status":"not_started","refreshed_sounds":null,"synced_at":null},"artists_label":"Example artist","image_url":null,"lists":[12],"expires_at":"2026-12-31T09:00:00Z","lookup":{"checked_at":"2026-10-02T09:00:00Z","recheck_after":null}}}],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"spotify_track_id":{"type":"string"},"spotify_uri":{"type":"string"},"track_id":{"type":["string","null"]},"title":{"type":["string","null"]},"status":{"type":"string"},"tracked_since":{"type":"string"},"refresh":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","warming_up","active"]},"refreshed_sounds":{"type":["integer","null"]},"synced_at":{"type":["string","null"]}},"required":["status","refreshed_sounds","synced_at"]},"artists_label":{"type":["string","null"]},"image_url":{"type":["string","null"]},"lists":{"anyOf":[{"type":"array","items":{}},{"type":"object","additionalProperties":{}}]},"expires_at":{"type":["string","null"]},"lookup":{"type":["object","null"],"properties":{"checked_at":{"type":["string","null"]},"recheck_after":{"type":["string","null"]}},"required":["checked_at","recheck_after"]}},"required":["id","spotify_track_id","spotify_uri","track_id","title","status","tracked_since","refresh","artists_label","image_url","lists","expires_at","lookup"]}},"required":["data"]}}},"headers":{"Retry-After":{"schema":{"type":"string"}}}},"201":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":{"id":"0199c3a2-5f1e-7c3b-9a4d-2e8f6b1c7d90","spotify_track_id":"0DWdj2oZMBFSzRsi2Cvfzf","spotify_uri":"spotify:track:0DWdj2oZMBFSzRsi2Cvfzf","track_id":"1fed0d6b-55bf-5e9e-b0b1-c765d3270258","title":"Example song","status":"active","tracked_since":"2026-10-01T12:00:00Z","refresh":{"status":"warming_up","refreshed_sounds":102,"synced_at":"2026-10-01T12:00:05Z"},"artists_label":"Example artist","image_url":null,"lists":[],"expires_at":null,"lookup":null}}],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"spotify_track_id":{"type":"string"},"spotify_uri":{"type":"string"},"track_id":{"type":["string","null"]},"title":{"type":["string","null"]},"status":{"type":"string"},"tracked_since":{"type":"string"},"refresh":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","warming_up","active"]},"refreshed_sounds":{"type":["integer","null"]},"synced_at":{"type":["string","null"]}},"required":["status","refreshed_sounds","synced_at"]},"artists_label":{"type":["string","null"]},"image_url":{"type":["string","null"]},"lists":{"anyOf":[{"type":"array","items":{}},{"type":"object","additionalProperties":{}}]},"expires_at":{"type":["string","null"]},"lookup":{"type":["object","null"],"properties":{"checked_at":{"type":["string","null"]},"recheck_after":{"type":["string","null"]}},"required":["checked_at","recheck_after"]}},"required":["id","spotify_track_id","spotify_uri","track_id","title","status","tracked_since","refresh","artists_label","image_url","lists","expires_at","lookup"]}},"required":["data"]}}}},"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"spotify_track_id":{"type":"string"},"spotify_uri":{"type":"string"},"track_id":{"type":["string","null"]},"title":{"type":["string","null"]},"status":{"type":"string"},"tracked_since":{"type":"string"},"refresh":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","warming_up","active"]},"refreshed_sounds":{"type":["integer","null"]},"synced_at":{"type":["string","null"]}},"required":["status","refreshed_sounds","synced_at"]},"artists_label":{"type":["string","null"]},"image_url":{"type":["string","null"]},"lists":{"anyOf":[{"type":"array","items":{}},{"type":"object","additionalProperties":{}}]},"expires_at":{"type":["string","null"]},"lookup":{"type":["object","null"],"properties":{"checked_at":{"type":["string","null"]},"recheck_after":{"type":["string","null"]}},"required":["checked_at","recheck_after"]}},"required":["id","spotify_track_id","spotify_uri","track_id","title","status","tracked_since","refresh","artists_label","image_url","lists","expires_at","lookup"]}},"required":["data"]},{"type":"string"}]}}}},"503":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"spotify_lookup_temporarily_unavailable","message":"Tokchart could not look this Spotify song up right now. Retry shortly."}],"properties":{"error":{"type":"string","const":"spotify_lookup_temporarily_unavailable"},"message":{"type":"string","const":"Tokchart could not look this Spotify song up right now. Retry shortly."}},"required":["error","message"]}}},"headers":{"Retry-After":{"schema":{"type":"string","const":"30"}}}},"404":{"description":"","content":{"application\/json":{"schema":{"examples":[{"error":"spotify_track_not_found","message":"Tokchart looked this Spotify song up and has no recording for it."}],"anyOf":[{"type":"object","properties":{"error":{"type":"string","const":"spotify_track_not_found"},"message":{"type":"string","const":"Tokchart looked this Spotify song up and has no recording for it."}},"required":["error","message"]},{"type":"object","properties":{"error":{"type":"string","const":"list_not_found"},"message":{"type":"string","const":"You have no list with this ID."}},"required":["error","message"]}]}}}},"409":{"description":"","content":{"application\/json":{"schema":{"examples":[{"error":"tracked_song_limit_reached","message":"Your tracked song limit has been reached.","limit":100}],"anyOf":[{"type":"object","properties":{"error":{"type":"string","const":"tracked_song_limit_reached"},"message":{"type":"string","const":"Your tracked song limit has been reached."},"limit":{"type":"string"}},"required":["error","message","limit"]},{"type":"object","properties":{"error":{"type":"string","const":"tracked_song_limit_reached"},"message":{"type":"string","const":"These songs do not fit your tracked song limit. Nothing was added."},"limit":{"type":"string"},"used":{"type":"integer","minimum":0}},"required":["error","message","limit","used"]}]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-songs\/{songId}":{"delete":{"operationId":"trackedSongs.destroy","description":"Requires the **Track songs and read their TikTok sounds** permission.","summary":"Stop tracking a song","tags":["Tracked Songs"],"parameters":[{"name":"songId","in":"path","required":true,"description":"The `id` of a song you track.","schema":{"type":"string"},"example":"0199c3a2-5f1e-7c3b-9a4d-2e8f6b1c7d90"}],"responses":{"204":{"description":"No content"},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"song_not_tracked"},"message":{"type":"string","const":"You are not tracking this song."}},"required":["error","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-songs\/{songId}\/sounds":{"get":{"operationId":"trackedSongs.sounds","description":"Requires the **Track songs and read their TikTok sounds** permission. The song includes `ugc_videos_per_day`, the last 30 completed UTC days of net new videos across all matched audios. Each entry has `date` and `count`; count is null when any audio lacks a baseline. Historical counts are carried forward between observations. Negative values reflect removals or corrections. No sounds gives an empty series.\n\nFollow `next_cursor` until it is null to read every sound: the pages add up to `meta.total_sounds`. Sounds TikTok has since removed are included with `is_removed: true` and their last observed stats.\n\nA song Tokchart has not identified yet returns 200 with its `status` (`pending` or `not_found`), no sounds and an empty `ugc_videos_per_day`.","summary":"Get a tracked song's TikTok sounds","tags":["Tracked Songs"],"parameters":[{"name":"songId","in":"path","required":true,"description":"The `id` of a song you track.","schema":{"type":"string"},"example":"0199c3a2-5f1e-7c3b-9a4d-2e8f6b1c7d90"},{"name":"cursor","in":"query","description":"The next_cursor from the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Sounds per page, from 1 to 250.","schema":{"type":"integer","default":100}}],"responses":{"404":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string","const":"track_not_found"},"message":{"type":"string","const":"The tracked recording is unavailable."}},"required":["error","message"]},{"type":"object","properties":{"error":{"type":"string","const":"song_not_tracked"},"message":{"type":"string","const":"You are not tracking this song."}},"required":["error","message"]}]}}}},"200":{"description":"","content":{"application\/json":{"schema":{"type":["array","null"],"examples":[{"track":{"id":"0199c3a2-5f1e-7c3b-9a4d-2e8f6b1c7d90","track_id":"1fed0d6b-55bf-5e9e-b0b1-c765d3270258","spotify_track_id":"0DWdj2oZMBFSzRsi2Cvfzf","title":"Example song","status":"active","tracked_since":"2026-10-01T12:00:00Z","refresh":{"status":"active","refreshed_sounds":102,"synced_at":"2026-10-02T02:45:00Z"},"lookup":null,"ugc_videos_per_day":[{"date":"2026-10-01","count":12500},{"date":"2026-10-02","count":null}]},"sounds":[],"next_cursor":null,"meta":{"total_sounds":0,"metrics_basis":"observed_videos"}}],"items":{}}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-songs\/imports":{"post":{"operationId":"playlistImports.store","description":"Requires the **Track songs and read their TikTok sounds** permission. Tokchart reads the playlist, which usually takes a few seconds. The import starts `loading` (202, with `Retry-After`), or `ready` (201) when Tokchart read the same playlist in the last hour. Read it with \"Get a playlist import\". Up to 500 songs are read; `playlist.truncated` is true when the playlist has more.\n\n503 `spotify_lookup_temporarily_unavailable` means the read could not start; retry after `Retry-After`.","summary":"Start a playlist import","tags":["Tracked Songs"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"spotify_playlist":{"type":"string","description":"Spotify playlist link, URI or 22-character ID.","examples":["https:\/\/open.spotify.com\/playlist\/37i9dQZF1DX4JAvHpjipBk"]}},"required":["spotify_playlist"]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"string"}}}},"503":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"error":"spotify_lookup_temporarily_unavailable","message":"Tokchart could not read this playlist right now. Retry shortly."}],"properties":{"error":{"type":"string","const":"spotify_lookup_temporarily_unavailable"},"message":{"type":"string","const":"Tokchart could not read this playlist right now. Retry shortly."}},"required":["error","message"]}}},"headers":{"Retry-After":{"schema":{"type":"string","const":"30"}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"202":{"description":"","content":{"application\/json":{"schema":{"type":"string","examples":[{"data":{"status":"loading","playlist":null,"songs":[],"id":"9d3c1f0e-7b1a-4c55-9a65-1f2e8f3a4b5c","spotify_playlist_id":"37i9dQZF1DX4JAvHpjipBk","requested_at":"2026-10-09T08:00:00Z","list_id":null}}]}}}},"201":{"description":"","content":{"application\/json":{"schema":{"type":"string","examples":[{"data":{"id":"9d3c1f0e-7b1a-4c55-9a65-1f2e8f3a4b5c","spotify_playlist_id":"37i9dQZF1DX4JAvHpjipBk","status":"ready","requested_at":"2026-10-09T08:00:00Z","list_id":null,"playlist":{"name":"New Music Friday","image_url":"https:\/\/i.scdn.co\/image\/ab67706f000000024a1e43f12da342b7da825bdc","owner":"Spotify","total":100,"truncated":false},"songs":[{"spotify_track_id":"5KTcGJKm4HgLhLt8Tc7EQ5","spotify_uri":"spotify:track:5KTcGJKm4HgLhLt8Tc7EQ5","title":"Draw You Out - From The Hunger Games: Sunrise on the Reaping - The Album","artists":[{"spotify_id":"2RQXRUsr4IW1f3mKyKsy4B","name":"Noah Kahan"},{"spotify_id":"6UdECsev3yuXe2rfLrdDiF","name":"The Hunger Games"}],"image_url":"https:\/\/i.scdn.co\/image\/ab67616d00001e02ff163890a7e96a400bc40b8a","spotify_streams":9007367,"is_playable":true,"explicit":false,"added_to_playlist_at":"2026-10-02T04:04:03Z","tracked_status":null}]}}]}}}}}}},"\/tiktok\/audio\/tracked-songs\/imports\/{importId}":{"get":{"operationId":"playlistImports.show","description":"Requires the **Track songs and read their TikTok sounds** permission. `status` is `loading`, `ready`, `not_found` (Spotify has no such public playlist) or `failed` (start a new import). While `loading`, the response is 202 with `Retry-After`. Each song has `spotify_streams`, its Spotify stream count when the playlist was read, and `tracked_status`: null when you do not track it yet, otherwise your song's `status`.","summary":"Get a playlist import","tags":["Tracked Songs"],"parameters":[{"name":"importId","in":"path","required":true,"description":"The import ID from \"Start a playlist import\".","schema":{"type":"string"},"example":"9d3c1f0e-7b1a-4c55-9a65-1f2e8f3a4b5c"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"string","examples":[{"data":{"id":"9d3c1f0e-7b1a-4c55-9a65-1f2e8f3a4b5c","spotify_playlist_id":"37i9dQZF1DX4JAvHpjipBk","status":"ready","requested_at":"2026-10-09T08:00:00Z","list_id":null,"playlist":{"name":"New Music Friday","image_url":"https:\/\/i.scdn.co\/image\/ab67706f000000024a1e43f12da342b7da825bdc","owner":"Spotify","total":100,"truncated":false},"songs":[{"spotify_track_id":"5KTcGJKm4HgLhLt8Tc7EQ5","spotify_uri":"spotify:track:5KTcGJKm4HgLhLt8Tc7EQ5","title":"Draw You Out - From The Hunger Games: Sunrise on the Reaping - The Album","artists":[{"spotify_id":"2RQXRUsr4IW1f3mKyKsy4B","name":"Noah Kahan"},{"spotify_id":"6UdECsev3yuXe2rfLrdDiF","name":"The Hunger Games"}],"image_url":"https:\/\/i.scdn.co\/image\/ab67616d00001e02ff163890a7e96a400bc40b8a","spotify_streams":9007367,"is_playable":true,"explicit":false,"added_to_playlist_at":"2026-10-02T04:04:03Z","tracked_status":null}]}}]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"playlist_import_not_found"},"message":{"type":"string","const":"You have no playlist import with this ID."}},"required":["error","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-songs\/imports\/{importId}\/songs":{"post":{"operationId":"playlistImports.addSongs","description":"Requires the **Track songs and read their TikTok sounds** permission. Adds every playable song of a `ready` import, or only `spotify_tracks`. By default the songs join a new list named after the playlist and today's date, and the list removes each song from your tracked songs `stop_after_days` (your account default, initially 90 days) after it joined; send `stop_after_days: null` for no end. Send `list_id` to use one of your lists, or `create_list: false` for no list. Calling it again adds to the same list.\n\nEvery song is added, or none when they do not fit your allowance (409). Songs Tokchart does not know yet are added as `pending` with the playlist's title, artists and cover, and become `active` once found. 409 `playlist_import_not_ready` means the import is not `ready`. 201 when at least one song was added, otherwise 200.","summary":"Add songs from a playlist import","tags":["Tracked Songs"],"parameters":[{"name":"importId","in":"path","required":true,"description":"The import ID.","schema":{"type":"string"},"example":"9d3c1f0e-7b1a-4c55-9a65-1f2e8f3a4b5c"}],"requestBody":{"content":{"application\/json":{"schema":{"type":"object","properties":{"spotify_tracks":{"type":"array","description":"Spotify IDs of songs in the playlist. Omit to add every playable song.","examples":[["5KTcGJKm4HgLhLt8Tc7EQ5"]],"items":{"type":"string","pattern":"^[A-Za-z0-9]{22}$"}},"list_id":{"type":"integer","description":"A list of yours that the songs join, instead of a new list."},"create_list":{"type":"boolean","description":"Whether the songs join a new list named after the playlist. Default true.","examples":[true]},"stop_after_days":{"type":"integer","description":"For a new list: remove each song from your tracked songs this many days after it joined (1 to 3650), or null for no end. Omit to use your account default (initially 90 days).","examples":[90]}}}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"string"}}}},"409":{"description":"","content":{"application\/json":{"schema":{"examples":[{"error":"tracked_song_limit_reached","message":"These songs do not fit your tracked song limit. Nothing was added.","limit":150,"used":112}],"anyOf":[{"type":"object","properties":{"error":{"type":"string","const":"tracked_song_limit_reached"},"message":{"type":"string","const":"These songs do not fit your tracked song limit. Nothing was added."},"limit":{"type":"string"},"used":{"type":"integer","minimum":0}},"required":["error","message","limit","used"]},{"type":"object","properties":{"error":{"type":"string","const":"playlist_import_not_ready"},"message":{"type":"string"},"status":{"type":"string"}},"required":["error","message","status"]}]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string","const":"list_not_found"},"message":{"type":"string","const":"You have no list with this ID."}},"required":["error","message"]},{"type":"object","properties":{"error":{"type":"string","const":"playlist_import_not_found"},"message":{"type":"string","const":"You have no playlist import with this ID."}},"required":["error","message"]}]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"201":{"description":"","content":{"application\/json":{"schema":{"type":"string","examples":[{"data":[],"meta":{"added":98,"already_tracked":2,"list":{"id":12,"name":"New Music Friday \u00b7 9 Oct","spotify_playlist_id":"37i9dQZF1DX4JAvHpjipBk","stop_after_days":90,"songs_count":100,"created_at":"2026-10-09T08:00:10Z"}}}]}}}}}}},"\/tiktok\/audio\/tracked-songs\/lists":{"get":{"operationId":"trackedSongLists.index","description":"Requires the **Track songs and read their TikTok sounds** permission. Newest first. Read a list's songs with \"List tracked songs\" and `list_id`.","summary":"List your song lists","tags":["Tracked Songs"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":[{"id":12,"name":"New Music Friday \u00b7 9 Oct","spotify_playlist_id":"37i9dQZF1DX4JAvHpjipBk","stop_after_days":90,"songs_count":100,"created_at":"2026-10-09T08:00:10Z"}]}],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"spotify_playlist_id":{"type":["string","null"]},"stop_after_days":{"type":["integer","null"]},"songs_count":{"type":"integer"},"created_at":{"type":"string"}},"required":["id","name","spotify_playlist_id","stop_after_days","songs_count","created_at"]}}},"required":["data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"post":{"operationId":"trackedSongLists.store","description":"Requires the **Track songs and read their TikTok sounds** permission. `stop_after_days` (1 to 3650) removes each song from your tracked songs that many days after it joined the list; omit it or send null for no end.","summary":"Create a song list","tags":["Tracked Songs"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Up to 120 characters.","examples":["Priority singles"]},"stop_after_days":{"type":"integer","description":"Days after joining that a song is removed from your tracked songs, or null for no end.","examples":[90]}},"required":["name"]}}}},"responses":{"201":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":{"spotify_playlist_id":null,"songs_count":0,"id":12,"name":"New Music Friday \u00b7 9 Oct","stop_after_days":90,"created_at":"2026-10-09T08:00:10Z"}}],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"spotify_playlist_id":{"type":["string","null"]},"stop_after_days":{"type":["integer","null"]},"songs_count":{"type":"integer"},"created_at":{"type":"string"}},"required":["id","name","spotify_playlist_id","stop_after_days","songs_count","created_at"]}},"required":["data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-songs\/lists\/{listId}":{"patch":{"operationId":"trackedSongLists.update","description":"Requires the **Track songs and read their TikTok sounds** permission. A new `stop_after_days` applies to every song in the list, counted from the day each song joined it.","summary":"Change a song list","tags":["Tracked Songs"],"parameters":[{"name":"listId","in":"path","required":true,"description":"The list ID.","schema":{"type":"integer"},"example":12}],"requestBody":{"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Up to 120 characters."},"stop_after_days":{"type":"integer","description":"Days after joining that a song is removed from your tracked songs, or null for no end.","examples":[30]}}}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":{"id":12,"name":"New Music Friday \u00b7 9 Oct","spotify_playlist_id":"37i9dQZF1DX4JAvHpjipBk","stop_after_days":90,"songs_count":100,"created_at":"2026-10-09T08:00:10Z"}}],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"spotify_playlist_id":{"type":["string","null"]},"stop_after_days":{"type":["integer","null"]},"songs_count":{"type":"integer"},"created_at":{"type":"string"}},"required":["id","name","spotify_playlist_id","stop_after_days","songs_count","created_at"]}},"required":["data"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"list_not_found"},"message":{"type":"string","const":"You have no list with this ID."}},"required":["error","message"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"delete":{"operationId":"trackedSongLists.destroy","description":"Requires the **Track songs and read their TikTok sounds** permission. Its songs stay tracked, and are no longer removed by this list. With `untrack_songs=true`, Tokchart also removes the list's songs that nothing else keeps.","summary":"Delete a song list","tags":["Tracked Songs"],"parameters":[{"name":"listId","in":"path","required":true,"description":"The list ID.","schema":{"type":"integer"},"example":12},{"name":"untrack_songs","in":"query","description":"Also remove the songs only this list kept.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"meta":{"untracked":98}}],"properties":{"meta":{"type":"object","properties":{"untracked":{"type":"integer"}},"required":["untracked"]}},"required":["meta"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"list_not_found"},"message":{"type":"string","const":"You have no list with this ID."}},"required":["error","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-songs\/lists\/{listId}\/songs":{"post":{"operationId":"trackedSongLists.addSongs","description":"Requires the **Track songs and read their TikTok sounds** permission. Every song must be one you track, given by its `id`; add new songs with \"Track a song\" and `list_id`. A song already in the list keeps the day it joined.","summary":"Add tracked songs to a list","tags":["Tracked Songs"],"parameters":[{"name":"listId","in":"path","required":true,"description":"The list ID.","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"song_ids":{"type":"array","description":"Up to 500 `id`s of songs you track.","examples":[["0199c3a2-5f1e-7c3b-9a4d-2e8f6b1c7d90"]],"items":{"type":"string","format":"uuid"}}},"required":["song_ids"]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"data":{"id":12,"name":"New Music Friday \u00b7 9 Oct","spotify_playlist_id":"37i9dQZF1DX4JAvHpjipBk","stop_after_days":90,"songs_count":100,"created_at":"2026-10-09T08:00:10Z"}}],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"spotify_playlist_id":{"type":["string","null"]},"stop_after_days":{"type":["integer","null"]},"songs_count":{"type":"integer"},"created_at":{"type":"string"}},"required":["id","name","spotify_playlist_id","stop_after_days","songs_count","created_at"]}},"required":["data"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"list_not_found"},"message":{"type":"string","const":"You have no list with this ID."}},"required":["error","message"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/tiktok\/audio\/tracked-songs\/lists\/{listId}\/songs\/{songId}":{"delete":{"operationId":"trackedSongLists.removeSong","description":"Requires the **Track songs and read their TikTok sounds** permission. The song stays tracked. 404 when it is not in the list.","summary":"Remove a song from a list","tags":["Tracked Songs"],"parameters":[{"name":"listId","in":"path","required":true,"description":"The list ID.","schema":{"type":"integer"},"example":12},{"name":"songId","in":"path","required":true,"description":"The `id` of a song in the list.","schema":{"type":"string"},"example":"0199c3a2-5f1e-7c3b-9a4d-2e8f6b1c7d90"}],"responses":{"204":{"description":"No content"},"404":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string","const":"song_not_in_list"},"message":{"type":"string","const":"This song is not in the list."}},"required":["error","message"]},{"type":"object","properties":{"error":{"type":"string","const":"list_not_found"},"message":{"type":"string","const":"You have no list with this ID."}},"required":["error","message"]}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/trending\/global":{"get":{"operationId":"trending.global","description":"Returns a paginated list of trending songs globally, ordered by chart position.\nRequires the **Read trending songs worldwide** permission.","summary":"Get trending songs globally","tags":["Trending Songs"],"parameters":[{"name":"page","in":"query","description":"Page number (starting from 1).","schema":{"type":"integer","default":1},"example":1},{"name":"page_size","in":"query","description":"Number of items per page (max 100).","schema":{"type":"integer","default":50},"example":50}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"items":[{"chart_index":1,"title":"Gata Only","artists":["floyymenor","Cris MJ"],"ugc_videos_total":25846806,"ugc_videos_per_day":36111},{"chart_index":2,"title":"Shiny","artists":["Easykid"],"ugc_videos_total":8318121,"ugc_videos_per_day":98786}],"total_items":198,"page":1,"page_size":50,"total_pages":4}],"properties":{"items":{"type":"array","prefixItems":[{"type":"object","properties":{"chart_index":{"type":"integer","const":1},"title":{"type":"string","const":"Gata Only"},"artists":{"type":"array","prefixItems":[{"type":"string","const":"floyymenor"},{"type":"string","const":"Cris MJ"}],"minItems":2,"maxItems":2,"additionalItems":false},"ugc_videos_total":{"type":"integer","const":25846806},"ugc_videos_per_day":{"type":"integer","const":36111}},"required":["chart_index","title","artists","ugc_videos_total","ugc_videos_per_day"]},{"type":"object","properties":{"chart_index":{"type":"integer","const":2},"title":{"type":"string","const":"Shiny"},"artists":{"type":"array","prefixItems":[{"type":"string","const":"Easykid"}],"minItems":1,"maxItems":1,"additionalItems":false},"ugc_videos_total":{"type":"integer","const":8318121},"ugc_videos_per_day":{"type":"integer","const":98786}},"required":["chart_index","title","artists","ugc_videos_total","ugc_videos_per_day"]}],"minItems":2,"maxItems":2,"additionalItems":false},"total_items":{"type":"integer","const":198},"page":{"type":"integer","const":1},"page_size":{"type":"integer","const":50},"total_pages":{"type":"integer","const":4}},"required":["items","total_items","page","page_size","total_pages"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/trending\/country\/{code}":{"get":{"operationId":"trending.country","description":"Returns a paginated list of trending songs for a specific country, ordered by chart position.\nRequires the Read trending songs permission for the requested country.","summary":"Get trending songs by country","tags":["Trending Songs"],"parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code, in any case. GB and UK both mean the United Kingdom.\n\nSupported codes:\n- DZ (Algeria)\n- AR (Argentina)\n- AU (Australia)\n- AT (Austria)\n- BD (Bangladesh)\n- BY (Belarus)\n- BE (Belgium)\n- BO (Bolivia)\n- BR (Brazil)\n- BG (Bulgaria)\n- CA (Canada)\n- CL (Chile)\n- CO (Colombia)\n- CR (Costa Rica)\n- CZ (Czech Republic)\n- DK (Denmark)\n- DO (Dominican Republic)\n- EC (Ecuador)\n- EG (Egypt)\n- SV (El Salvador)\n- EE (Estonia)\n- FI (Finland)\n- FR (France)\n- DE (Germany)\n- GR (Greece)\n- GT (Guatemala)\n- HN (Honduras)\n- HK (Hong Kong)\n- HU (Hungary)\n- IN (India)\n- ID (Indonesia)\n- IE (Ireland)\n- IL (Israel)\n- IT (Italy)\n- JP (Japan)\n- KZ (Kazakstan)\n- KE (Kenya)\n- MY (Malaysia)\n- MX (Mexico)\n- MA (Morocco)\n- MM (Myanmar)\n- NL (Netherlands)\n- NI (Nicaragua)\n- NG (Nigeria)\n- NO (Norway)\n- PK (Pakistan)\n- PA (Panama)\n- PY (Paraguay)\n- PE (Peru)\n- PH (Philippines)\n- PL (Poland)\n- PT (Portugal)\n- RO (Romania)\n- RU (Russia)\n- SA (Saudi Arabia)\n- SG (Singapore)\n- SK (Slovakia)\n- ZA (South Africa)\n- KR (South Korea)\n- ES (Spain)\n- SE (Sweden)\n- CH (Switzerland)\n- TW (Taiwan)\n- TH (Thailand)\n- TR (Turkey)\n- UA (Ukraine)\n- AE (United Arab Emirates)\n- UK (United Kingdom)\n- US (United States)\n- UY (Uruguay)\n- VE (Venezuela)\n- VN (Vietnam)","schema":{"type":"string","enum":["DZ","AR","AU","AT","BD","BY","BE","BO","BR","BG","CA","CL","CO","CR","CZ","DK","DO","EC","EG","SV","EE","FI","FR","DE","GR","GT","HN","HK","HU","IN","ID","IE","IL","IT","JP","KZ","KE","MY","MX","MA","MM","NL","NI","NG","NO","PK","PA","PY","PE","PH","PL","PT","RO","RU","SA","SG","SK","ZA","KR","ES","SE","CH","TW","TH","TR","UA","AE","UK","US","UY","VE","VN"],"examples":["DZ"]},"example":"DZ"},{"name":"page","in":"query","description":"Page number (starting from 1).","schema":{"type":"integer","default":1},"example":1},{"name":"page_size","in":"query","description":"Number of items per page (max 100).","schema":{"type":"integer","default":50},"example":50}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","examples":[{"items":[{"chart_index":1,"title":"Never Leave You (Uh Oooh, Uh Oooh) [Mixed]","artists":["Lumidee"],"ugc_videos_total":259725,"ugc_videos_per_day":-710},{"chart_index":2,"title":"That's So True","artists":["Gracie Abrams"],"ugc_videos_total":47559638,"ugc_videos_per_day":-246034}],"total_items":147,"page":1,"page_size":50,"total_pages":3}],"properties":{"items":{"type":"array","prefixItems":[{"type":"object","properties":{"chart_index":{"type":"integer","const":1},"title":{"type":"string","const":"Never Leave You (Uh Oooh, Uh Oooh) [Mixed]"},"artists":{"type":"array","prefixItems":[{"type":"string","const":"Lumidee"}],"minItems":1,"maxItems":1,"additionalItems":false},"ugc_videos_total":{"type":"integer","const":259725},"ugc_videos_per_day":{"type":"string"}},"required":["chart_index","title","artists","ugc_videos_total","ugc_videos_per_day"]},{"type":"object","properties":{"chart_index":{"type":"integer","const":2},"title":{"type":"string","const":"That's So True"},"artists":{"type":"array","prefixItems":[{"type":"string","const":"Gracie Abrams"}],"minItems":1,"maxItems":1,"additionalItems":false},"ugc_videos_total":{"type":"integer","const":47559638},"ugc_videos_per_day":{"type":"string"}},"required":["chart_index","title","artists","ugc_videos_total","ugc_videos_per_day"]}],"minItems":2,"maxItems":2,"additionalItems":false},"total_items":{"type":"integer","const":147},"page":{"type":"integer","const":1},"page_size":{"type":"integer","const":50},"total_pages":{"type":"integer","const":3}},"required":["items","total_items","page","page_size","total_pages"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}}},"components":{"securitySchemes":{"http":{"type":"http","scheme":"bearer","bearerFormat":"sanctum"}},"responses":{"ValidationException":{"description":"Validation error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Errors overview."},"errors":{"type":"object","description":"A detailed description of each field that failed validation.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["message","errors"]}}}},"AuthenticationException":{"description":"Unauthenticated","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}}}},"ModelNotFoundException":{"description":"Not found","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}}}}}}}