List videos under a hashtag
Videos posted under a hashtag, plus the hashtag itself — its id, name, url, description, cover image, view count and video count. The view count is the hashtag’s own total across TikTok, which is how you size a trend before deciding how much of it to read. Page with pages and cursor. A hashtag with no public videos returns an explained empty result in notes. Billing: 1 credit per page read.
/hashtag-videos Search & hashtags https://api.fetchlayer.dev/tiktok/hashtag-videos Headers
Authorization string required Bearer token — your FetchLayer API key.
Parameters
hashtag string required A hashtag name with or without the leading #, or a hashtag URL.
limit integer optional Maximum videos returned, up to 500. Use -1 for the maximum. (default: 30)
pages integer optional Pages of results to read in one request, up to 20. Use -1 for the maximum. Each page read is one billable page, and the response reports how many were read as pagesFetched. (default: 1)
cursor string optional Continue from a previous response’s nextCursor. Cursors belong to the route and the query that produced them — do not carry one between routes.
format string optional json or markdown. Markdown returns a rendered summary instead of the structured record. (default: json)
timeoutMs integer optional Time limit for each individual page read, in milliseconds (max 60000). It bounds one page, not the whole request.
Response Fields
hashtag-videos
List videos under a hashtag
transport string The upstream source. Always "tiktok".
notes string[] 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.
pagesFetched number Pages of results read, which is what the request costs: one credit per page. resolve-url reports 0 and is not billed.
hashtag.id string TikTok’s numeric hashtag id.
hashtag.name string The tag, without the #.
hashtag.url string Canonical hashtag URL.
hashtag.description string The tag’s description, or null.
hashtag.coverUrl string Cover image, or null.
hashtag.viewCount number Total views across TikTok for the tag, or null when it publishes none.
hashtag.videoCount number Videos TikTok reports under the tag, or null.
videos object[] The videos posted under it.
videos[].id string Numeric video id, which video-detail and comments both accept.
videos[].url string Canonical link to the video. This is what you use to open or embed it.
videos[].description string The caption, or null when there is none.
videos[].createdAt string ISO 8601 timestamp of when it was posted, or null.
videos[].durationSeconds number Length in seconds, or null.
videos[].isPhotoPost boolean True for a photo carousel rather than a clip.
videos[].coverUrl string The cover frame. An image, so it re-fetches through GET /media normally.
videos[].assets object[] 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.
videos[].assets[].downloadUrl string Pass it to GET /media to stream the bytes. It serves images — carousel frames and cover images. A clip's bytes cannot be fetched by anyone, so asking for one returns 404 (see the media endpoint).
videos[].stats object playCount, diggCount, commentCount, shareCount, collectCount and repostCount. A null counter means TikTok did not publish that figure; a real zero comes back as 0.
videos[].author object id, uniqueId, nickname, avatarUrl, signature, verified, privateAccount, profileUrl and secUid.
videos[].music object id, title, authorName, durationSeconds, original, coverUrl, playUrl and url, or null.
videos[].hashtags string[] Without the #, read from TikTok’s own annotations rather than parsed out of the caption.
videos[].mentions string[] Usernames without the @.
videos[].isAd boolean True when TikTok marks the post as promotional, or null when it says nothing.
videos[].language string The language TikTok assigned to the caption, or null.
videoCount number How many videos are in this response.
hasMore boolean Whether more results exist beyond what was returned.
nextCursor string Opaque value to pass back as cursor to continue. null when there is nothing further.
Request
curl -X POST "https://api.fetchlayer.dev/tiktok/hashtag-videos" \
-H "Authorization: Bearer ss-your-key" \
-H "Content-Type: application/json" \
-d '{"hashtag":"nasa","limit":30}'Response
{
"transport": "tiktok",
"notes": [],
"pagesFetched": 1,
"hashtag": {
"id": "3301",
"name": "nasa",
"url": "https://www.tiktok.com/tag/nasa",
"description": null,
"coverUrl": null,
"viewCount": 56600000000,
"videoCount": 0
},
"videos": [
{
"id": "7686148096895569165",
"url": "https://www.tiktok.com/@nasa/video/7686148096895569165",
"description": "Turns out you can dance in space! 🪩🕺💫🛰️ Microgravity just unlocked some new moves.",
"createdAt": "2026-09-16T15:00:41.000Z",
"durationSeconds": 58,
"isPhotoPost": false,
"coverUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/...",
"assets": [
{
"kind": "video",
"url": "https://v16-webapp-prime.us.tiktok.com/video/tos/useast5/...",
"width": 720,
"height": 1280,
"downloadUrl": "https://api.fetchlayer.dev/tiktok/media?url=..."
}
],
"stats": {
"playCount": 27600,
"diggCount": 4367,
"commentCount": 173,
"shareCount": 104,
"collectCount": 273,
"repostCount": 0
},
"author": {
"id": "7664638705177150477",
"uniqueId": "nasa",
"nickname": "NASA",
"verified": true,
"privateAccount": false,
"profileUrl": "https://www.tiktok.com/@nasa"
},
"music": {
"id": "7686148224364694286",
"title": "original sound - NASA",
"authorName": "NASA",
"durationSeconds": 58,
"original": false,
"url": "https://www.tiktok.com/music/x-7686148224364694286"
},
"hashtags": [],
"mentions": [],
"isAd": false,
"language": "en"
}
],
"videoCount": 30,
"hasMore": true,
"nextCursor": "30"
}