TikTok API v1

Available endpoints

One video shape, everywhere

Every route that returns videos returns the same record, so code written against a search result works unchanged on an account's posts or a hashtag feed: id, url, description (the caption), createdAt, durationSeconds, isPhotoPost, coverUrl, assets, stats, author, music, hashtags, mentions, isAd and language.

assets is an ordered list, which is how a clip and a photo carousel are handled the same way: a clip yields one asset of kind video, a carousel one of kind image per frame. Hashtags and mentions come from TikTok's own annotations on the post, not from parsing the caption, so a tag written inside a word does not produce a false positive.

Media: images and covers, not video files

TikTok's own asset URLs are signed and expire within hours, so every asset carries a downloadUrl pointing at GET /media instead, which re-fetches it on demand with Range support.

Video bytes cannot be downloaded, by anyone. TikTok answers an ordinary request for a clip's URL with a 403 regardless of who asks — including from the page that produced the URL — so only its own player can read those bytes. This endpoint therefore serves images: photo-post frames, cover frames and avatars, which fetch normally. A clip's url is still returned on the video, and that is what you use to open or embed it; asking /media for one returns a 404 saying the source refused it. No service reading the public site can hand over a video file, and this one does not claim to.

Paging and billing

limit caps the items returned; pages caps how many pages are read to get them, up to 20. When more results exist, hasMore is true and nextCursor carries an opaque value to pass back as cursor. Cursors belong to the route and query that produced them — do not carry one between routes. Passing -1 on limit or pages means "the maximum this service allows", which is 500 videos, 500 comments and 20 pages.

Billing follows pages: one credit per page of results read, and every response states it as pagesFetched. A single-page request costs 1. /resolve-url reaches TikTok not at all, reports pagesFetched: 0 and is free.

Read the notes array

Every response carries notes, and an empty result always comes with one explaining it rather than as an unexplained empty array. The ones you will see: a list that stopped before the requested number was reached; paging that has gone as deep as it goes; a comment that has more replies than are listed; a private account; a video with comments turned off; and a genuinely empty account, hashtag or search.

A null counter means TikTok did not publish that figure, not zero — a real zero comes back as 0. The distinction is preserved everywhere, so a missing value is never reported as an absence of engagement.

Requests are strict

An unrecognised body field is a 400 naming it, not a silent no-op. A typo such as hashtagNam would otherwise be dropped and answered with the wrong data and no indication why. The same principle is why search takes no sort order and no date filter: TikTok offers a public caller neither, so they are rejected rather than accepted and ignored.

What this API does not return

• Downloadable video bytes. See above: TikTok refuses a clip's bytes to every caller. Clip URLs, photo-post images and cover images are all returned.
• Follower and following lists. Not in this release.
• Full comment reply threads. Only the replies TikTok inlines with a comment; replyCount reports the true total.
• Sound and music pages, and the videos using a sound. Not in this release — a sound link still resolves through /resolve-url.
• Trending and discover feeds, and video transcripts or subtitles. Not in this release.
• Account analytics — audience demographics, watch time, traffic sources. TikTok publishes none of this for an account you do not own, so no service can return it for an arbitrary creator.
• Historical snapshots. Counts are as at the time of the request; there is no time series. Store what you read if you want one.
• A date filter or sort on search. TikTok offers a public caller neither.

Advertising, separately

This API reads organic TikTok. For the paid side — the ads a brand is running, their creative and the advertisers behind them — see the TikTok Ad Library API, which is a separate platform on the same key.