GET/social-media/{socialMediaId}/tiktok-sounds

Returns TikTok's trending, pre-cleared sounds for a connected TikTok account, ranked by a genre, country, and time window you choose. Use the musicSoundId field as tiktokMusicSoundId when creating a TikTok photo carousel.

https://api.postfa.st/Auth: pf-api-keyRate limit: 90 requests per hour

Usage

Pass the musicSoundId you picked as tiktokMusicSoundId in the controls object on POST /social-posts. TikTok attaches the audio server-side at publish, so you never download, host, or upload the track yourself.

The optional tiktokMusicSoundName control is a display label for your own UI ("Track - Artist"). It is stored with the post and never sent to TikTok.

Photo carousels only

A selected sound applies to TikTok photo carousels. It is ignored on drafts (tiktokIsDraft: true), because TikTok only accepts a title and caption on a draft.

It is also mutually exclusive with tiktokAutoAddMusic: setting both returns 400 tiktokMusic.conflictAutoAddMusic. Pick a sound, let TikTok pick one, or send neither and the post publishes silent.

Licensing and freshness

Every track returned is from TikTok's Commercial Music Library, so it is already cleared for business use. Tracks outside that library cannot be attached through the API.

The trending list rotates roughly daily and each genre/country/date-range combination is cached about 6 hours server-side. Resolve a sound close to when you schedule: ids stay valid, but rank positions move.

Reconnect an older TikTok account

A TikTok account connected some time ago returns 400 tiktokMusic.requiresBusinessApi on this endpoint. Reconnect it once from the Accounts page in your PostFast dashboard and both this endpoint and tiktokMusicSoundId start working. Newly connected accounts need nothing.

Path parameters

socialMediaIdstring (UUID)required

The id of the connected TikTok account, from /social-media/my-social-accounts.

Query parameters

genrestringoptionaldefault ALL

Rank within one TikTok genre, e.g. POP or K-POP. TikTok publishes 110 genre values and they are passed through raw, so the ones containing / or & (HIP_HOP/RAP, R&B/SOUL) must be URL-encoded. An unrecognized value returns 400 tiktokSounds.invalidGenre.

countryCodestringoptionaldefault US

Two-letter uppercase location code, e.g. DE. Trending sounds differ per country. A well-formed code that TikTok has no chart for returns 200 with an empty array rather than an error; a malformed one returns 400 tiktokSounds.invalidCountryCode.

dateRangestringoptionaldefault 7DAY

The trending window the ranking is computed over.

1DAY7DAY30DAY90DAY

Errors

SituationResponse
TikTok account needs a one-time reconnect400 tiktokMusic.requiresBusinessApi
Unrecognized genre400 tiktokSounds.invalidGenre
dateRange outside 1DAY/7DAY/30DAY/90DAY400 tiktokSounds.invalidDateRange
Malformed countryCode400 tiktokSounds.invalidCountryCode
socialMediaId is not a TikTok account, or not in this workspace404 tiktokSounds.socialMediaNotFound

A valid countryCode that TikTok has no chart for is not an error: it returns 200 with an empty array.

Response

200 OK Up to 100 sounds, already ordered by trending rank. There is no pagination and no page/limit param: request the slice you want with genre, countryCode, and dateRange, then filter the rest client-side.

musicSoundIdstringoptional

TikTok's id for the sound. This is the only field you need to attach it: pass it as tiktokMusicSoundId in the controls object on /social-posts.

namestringoptional

Track title.

artiststringoptional

Artist name.

durationnumberoptional

Length in seconds of the exact clip musicSoundId refers to, not of the full track.

thumbnailUrlstringoptional

Cover art, served from TikTok's CDN and safe to hotlink in a picker UI.

previewUrlstringoptional

Audio preview. It plays the exact clip that will be attached, so what a user hears in your picker is what publishes.

rankPositionnumberoptional

Position in the trending list for the requested genre, country, and date range. 1 is the top sound.

genresstring[]optional

The genres TikTok assigns to the track. A track can sit in more than one, so this need not equal the genre you filtered by.

commercialMusicIdstringoptional

Advanced: TikTok's Commercial Music Library id for the track.

fullDurationClipIdstringoptional

Advanced: id of the full-length clip.

trendingClipIdstringoptional

Advanced: id of the trimmed clip that is trending. Attaching a sound never needs this.