Search TikTok videos
Videos matching a search term, in TikTok's own ranking for it. There is no sort order and no date filter, because TikTok offers a public caller neither — passing one is a 400 naming the field rather than a parameter that is accepted and quietly ignored, which would hand you the wrong data with no indication why. Up to 500 videos and 20 pages in one request; when a list runs out before the requested number, notes says so and what was collected comes back. Billing: 1 credit per page read.
/search-videos Search & hashtags https://api.fetchlayer.dev/tiktok/search-videos Headers
Authorization string required Bearer token — your FetchLayer API key.
Parameters
query string required What to search TikTok for.
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
search-videos
Search TikTok videos
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.
query string The term that was searched.
videos object[] The matching videos, in TikTok’s ranking.
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/search-videos" \
-H "Authorization: Bearer ss-your-key" \
-H "Content-Type: application/json" \
-d '{"query":"space launch","limit":30}'Response
{
"transport": "tiktok",
"notes": [],
"pagesFetched": 1,
"query": "space launch",
"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"
}