List videos under a hashtag

The data source: always the platform id, "tiktok".

Caveats you can act on — a private account, comments turned off, a list that ran out early, paging that has gone as deep as it goes. Empty when there are none. An empty result always comes with a note explaining it, never as an unexplained empty array.

Pages of results fetched, search pages included. It is not what this route bills: that is 1 credit per page of up to 30 posts delivered, stated as credits.

TikTok’s numeric hashtag id.

The tag, without the #.

Canonical hashtag URL.

The tag’s description, or null.

Cover image, or null.

Total views across TikTok for the tag, exact, or null when it publishes none.

Videos TikTok reports under the tag, exact, or null.

Which hashtag counts are rounded. Normally empty: both counts are exact.

The videos TikTok lists under it. What TikTok lists for a hashtag: popular posts first, not newest first — a post published a minute ago can sit behind years-old ones, and there is no date order. Only roughly the top 170 to 200 posts, then TikTok says there are no more, even for hashtags with millions of posts. A topic feed: between a quarter and nine tenths of the listed posts carry the tag in their own caption (each video’s hashtags says which). Two requests a minute apart share about 70–95% of their posts, in a somewhat different order; most of the rest are older posts TikTok rotates in and out of its selection. Empty for a hashtag with no public videos, with the note "This hashtag has no public videos." TikTok ends the list for a few very broad hashtags after a handful of videos (#fyp lists 1 to 3); the response then has hasMore false and a note giving both numbers.

Present only when since, knownIds, lastPollAt, within, requireHashtag, pollState or includeSearch is set. true: published at or after lastPollAt (or since). false: older (inside within, if it was sent) and not in knownIds, so newly appeared — mostly TikTok rotating its selection rather than a new post. null: cannot be told — no lastPollAt or since, no date from TikTok, or an older post when knownIds was not sent.

Present only with includeSearch: list for a post from the hashtag’s own list, search for one a search for the hashtag found that the list did not include.

Present only when since, knownIds, lastPollAt, within, requireHashtag, pollState or includeSearch is set: scannedCount (posts checked in the hashtag’s list, returned or not), excludedCount (left out because they were in knownIds, posted before since or the within window, or did not carry the hashtag with requireHashtag), excludedOlderCount (of those, the ones posted before since or the window), olderFloorAt (where the within window started, ISO 8601; null without within), newlyPublishedCount and newlyAppearedCount. videoCount then counts only the posts returned. limit counts posts returned, not those left out, and pages still bounds how far down the list a request goes. These options narrow what TikTok lists; they cannot find a new post TikTok does not list. When nothing new is listed, videos is empty with a note, and that is the answer, not a failure.

Posts checked in the hashtag’s list, returned or not.

Left out because they were in knownIds, posted before since or the within window, or did not carry the hashtag with requireHashtag.

Present only with includeSearch: the posts checked and returned from each source, as list and search.

Posts checked from the hashtag’s list.

Of those, posts returned.

Posts checked from the search for the hashtag.

Of those, posts returned.

Of excludedCount, the posts left out by requireHashtag for not carrying the hashtag in their own caption.

Of excludedCount, those posted before since or the within window.

Where the within window started, as an ISO 8601 date-time; posts published before it were left out. null without within.

Returned posts with newlyPublished true.

Returned posts with newlyPublished false.

Numeric video id, which video-detail and comments both accept.

Canonical link to the video. This is what you use to open or embed it.

The caption, or null when there is none.

ISO 8601 timestamp of when it was posted, or null.

Length in seconds, or null.

True for a photo carousel rather than a clip.

The cover frame. An image, so it re-fetches through GET /media normally.

An ordered list, so a clip and a carousel are handled the same way: a clip yields one asset of kind "video", a carousel one of kind "image" per frame. Each carries url, width, height and downloadUrl. A video asset’s url is TikTok’s own link, which expires within hours and does not open on its own; use downloadUrl. Every post has a video or images, so an empty list means its media could not be read this time: on a request with include, the video then lists assets in missingFields and the page has complete false with a missing entry {field: "assets", reason: "failed", count}.

A https://api.fetchlayer.dev/tiktok/media link that keeps working after TikTok’s own link expires. On a video asset it is ?video=<id> and delivers the video as an MP4 without the TikTok watermark; it is null when the creator has turned off downloads. On an image asset it is ?url=… and delivers the image. Each request to it costs 1 credit.

playCount, diggCount, commentCount, shareCount, collectCount and repostCount. A null counter means TikTok did not publish that figure; a real zero comes back as 0. Views, likes, comments and shares are rounded once they reach 10,000 — roundedStats says which. Counts are as TikTok shows them to US viewers. TikTok keeps a copy of the counts for each region, and the copies differ by a few units, so successive requests can differ slightly.

Which counters in stats TikTok publishes only rounded: to the nearest 100 from 10,000, the nearest 100,000 from 1M, the nearest 100M from 1B. Empty means every counter is exact. Saves (collectCount) are always exact.

id, uniqueId, nickname, avatarUrl, signature, verified, privateAccount, profileUrl and secUid.

id, title, authorName, durationSeconds, original, coverUrl, playUrl and url, or null.

Without the #, as TikTok tags them on the post rather than parsed out of the caption.

Usernames without the @.

Every account tagged in the caption, in caption order: username, userId (an exact string), secUid, text, start, end and unresolved, each null when TikTok published no value — so username and secUid can be null.

null when the tag leads to an account. "account_unavailable" when TikTok names the account’s userId but no longer publishes its username or secUid — the account was deleted, banned or is otherwise unavailable; userId, text, start and end still come back, for example {"username": null, "userId": "6794638798661157893", "secUid": null, "text": "@Weight Watchers", "start": 17, "end": 33, "unresolved": "account_unavailable"}. "not_published" when TikTok published no account id for the tag.

The tag as the caption shows it, including the @. Often the display name rather than the username: "@E.L.F Cosmetics" tags eyeslipsfacecosmetics. Use username, userId or secUid to identify the account.

Where the tag starts in description; end is where it stops, exclusive. Both count UTF-16 code units, so description.slice(start, end) equals text in JavaScript; in Python, slice the UTF-16 encoding.

Every hashtag in the caption, with id (or null), name without the #, text with it, and start and end counted like mentionedUsers.

TikTok’s own isAd value: true when TikTok runs or has run the post as a promoted ad, null when TikTok sends no value. Not the creator’s own #ad disclosure. The three flags combine freely: a post can be an ad and a paid partnership, or a partnership that is also shoppable.

True when the post carries TikTok’s paid-partnership label, which is exactly when commercialSignals.adLabelVersion is 2. False when it is unmarked.

True for a shop or product video: commercialSignals.isECVideo is above 0, or the post carries TikTok’s e-commerce link type 33. False when it is unmarked.

TikTok’s own values behind isPaidPartnership and isShoppable, exactly as TikTok publishes them, for callers who want the numbers. null means TikTok sent no value for the post. TikTok does not publish an ad-type or branded-content code beyond these.

TikTok’s ad-label value, or null. 2 is its paid-partnership label, and isPaidPartnership is true exactly when this is 2.

TikTok’s own branded/organic code, such as 1001, or null. TikTok does not explain what the codes mean, and 1001 appears on ads, partnership posts and some unmarked posts alike, so treat it as informational, not as a flag.

Above 0 (seen: 1) when TikTok marks the post as a shop or product video; null when TikTok sends no value.

True when the creator allowed the post to be used in ads, or null. Not a sign that it is running as an ad.

TikTok’s type codes for the links attached to the post: 35 a product link (always with isECVideo 1), 54 an editing-app link, 28 an effect link. Other codes are passed through as TikTok sends them. Empty when no links are attached.

The two-letter region TikTok records this post as created in, such as "US". Filled on video-detail; on user-videos, search-videos and hashtag-videos it is null unless the request has include: ["createdRegion"]. Not the account’s region.

The language TikTok assigned to the caption, or null.

Only with include ["exactStats"]: the exact counts — playCount, diggCount, commentCount, shareCount and collectCount — as whole numbers, never rounded, where stats rounds from 10,000 up. null, with a note, when they could not be filled. Exact counts are filled for nearly all posts — about 19 in 20 resolve, most on the first ask. The rest come back null with a note; asking again later can fill them. A miss is a normal 200, not an error: the video comes back in full with its usual stats (six counts, including repostCount) and roundedStats, and exactStats, isAdsNative, brandedContentType and accountRegion are present and null, with a note — so check exactStats === null rather than the HTTP status. exactStats has five counts; it has no repostCount. On a list, a page can be partly filled: a note gives how many videos are null, and video-detail can fill those one at a time. The notes read, verbatim: “The exact counts could not be found for this video, so exactStats and accountRegion are null; ask again shortly.”; when your timeoutMs ran out first, “The exact counts could not be filled in time, so exactStats and accountRegion are null; ask again, or allow more time.”; on a list, “The exact counts could not be filled for N of these M videos in time, so exactStats is null for them; ask again or use video-detail for those videos.”; and when only the region is missing, “The exact counts were filled, but this account’s registered region did not come with them, so accountRegion is null.”

Exact views.

Exact likes.

Exact comments.

Exact shares.

Exact saves.

Only with include ["exactStats"]: TikTok’s own ad marker for the post. true is rare; false and null are what nearly every post carries.

Only with include ["exactStats"]: TikTok’s numeric branded-content type — 0 none, 1 paid partnership, 7 commission; other codes come through as TikTok sends them (4 has been seen). null when not filled.

Only with include ["exactStats"]: the two-letter region TikTok records the account as registered in, such as "US" — the account’s own country. Not where this post was made (createdRegion), and not where the account’s recent videos were posted (postingRegion on user-profile); the three can differ. null, with a note, when no region came with the exact counts, so exactStats can be filled while this is null.

Only on a request with include: the fields asked for (exactStats, accountRegion, createdRegion) that this video was left without, and assets when its media could not be read (its assets list is then empty); empty when it has them all. A field TikTok does not publish for the post, such as a post with no recorded created-in region, is not listed.

Only on a request with include: true when every video has every field asked for. A 200 with complete false still carries every video: count it as a delivered response with fields to ask for again, not as a failure.

Only on a request with include: one entry per field and reason, as {field, count, reason}, counting the videos left without it; empty when complete.

exactStats, accountRegion, createdRegion or assets. assets counts the videos whose media could not be read, so their assets list is empty; ask again for them. exactStats missing means isAdsNative, brandedContentType and accountRegion are null too; accountRegion on its own means the exact counts filled and only the account’s region did not come with them.

How many videos were left without that field, for that reason.

time_limit: the time limit ran out before it was filled (your timeoutMs, or the default when you set none); ask again, or allow more time. not_found: it was looked up and not found this time; ask again later. failed: the lookup failed; ask again. unavailable: not offered on this request. New reasons may be added, so treat an unknown one as “not filled”. createdRegion is only ever time_limit or failed; accountRegion is only ever not_found; assets is only ever failed; exactStats can carry any of the four.

How many videos are in this response, list and search posts alike. credits is what the request is billed for them.

Whether more results exist beyond what was returned.

An opaque token (tt1.…) to pass back unchanged as cursor, with the same request, to continue exactly where this response stopped. Continuing never repeats or skips a video: with sort latest on user-videos, every video comes back once, newest first. With sort popular, on search and on hashtags the same holds at each boundary, but TikTok can re-rank between requests, so keep the ids you have if every video exactly once across a long walk matters. null when there is nothing further.

Present only when the request sent pollState: send it as pollState on your next poll of this hashtag.

Why the list stopped. With a nextCursor to continue: limit (as many posts as limit asked for), pages (the pages limit was reached), time (your timeoutMs would not fit another page), interrupted (TikTok did not return the next page). Without one: end (the end of what TikTok lists for this hashtag, at most about 170–200 posts). cut_short: TikTok ended the list early, well short of what it reports for the hashtag. Asking again often returns more, and when this response got any posts it carries a nextCursor that continues from where it stopped, with hasMore true; a continuation that gets nothing ends without one. When a list is cut short, follow its nextCursor once. If that continuation comes back with no posts and cut_short (and no cursor), do not repeat it: TikTok stopped listing the hashtag there for this request. Wait a little and poll the hashtag again from the start, with your latest pollState if you use one; the list changes between requests, and a later poll usually goes deeper. A request whose list is cut short has already been retried up to twice before it answers.

What this request is billed: 1 credit per page of up to 30 posts delivered; minimum 1 credit per request (a poll delivering nothing new costs the base request charge). The whole list of a hashtag (about 170 posts) is about 6; a poll that delivers a few new posts is 1–2; a poll with nothing new is 1. Every request is billed at least 1, including a repeated request and a continuation with a cursor.