How do I search TikTok videos by keyword?
Call GET /v1/tiktok/search/posts?q=…. Each request returns one page of public videos matching the keyword, with the author, caption, timestamp, and views, likes, comments, shares, and saves. Pass the cursor back for the next page.
Search returns what TikTok shows a logged-out visitor now. There is no archive and no date filter. For history, run the search on a schedule and store IDs.
Checked September 2026 · request and response run against the API · no affiliate links
curl "https://api.openhandle.dev/v1/tiktok/search/posts?q=synthetic" \
-H "Authorization: Bearer $OPENHANDLE_API_KEY"import { OpenHandle } from '@openhandle/sdk';
const openhandle = new OpenHandle({ apiKey: process.env.OPENHANDLE_API_KEY! });
let page = await openhandle.tiktok.search.posts.list({ q: 'synthetic' });
while (page) {
for (const video of page.data) console.log(video.author.handle, video.metrics.views);
page = await page.next();
}{
"platform": "tiktok",
"resource": "post",
"capturedAt": "2026-09-18T12:10:14Z",
"source": "live",
"data": [
{
"id": "920100000000000001",
"caption": "A synthetic orchard loop. #pixelorchard",
"createdAt": "2026-08-09T15:30:00Z",
"author": { "id": "920000000001", "handle": "pixel_orchard_tt_test" },
"metrics": { "views": 23000, "likes": 1200, "comments": 24, "shares": 73, "saves": 88 }
}
],
"meta": { "cursors": { "next": "b3BhcXVlLWN1cnNvcg" } }
}Trimmed to one video. The full record has media renditions, sound, hashtags, and more. The example is a Test fixture, so you can run it on a free Test key.
Other searches
- —Profiles.
GET /v1/tiktok/search/profiles?q=…finds creators by name or handle. - —Hashtags.
GET /v1/tiktok/search/hashtags?q=…finds hashtags with their post counts. Then list the hashtag’s videos. - —Sounds.
GET /v1/tiktok/search/music?q=…finds sounds. Then list the videos that use one. - —Places.
GET /v1/tiktok/search/locations?q=…finds places. Then list videos tagged there.
Why the official APIs do not do this
The TikTok Research API has a query endpoint, for approved academic and non-profit researchers only. The Display API has no search at all. For a brand, an agency, or a product, keyword search across public TikTok is a public data API job.
Monitor a keyword over time
Run the search on a schedule, store each video id, and skip IDs you already have. Store capturedAt with each run. Re-read a video later with GET /v1/tiktok/posts/{id} to update its metrics. Views on a fresh video are low for a while. A metric TikTok has not published is null, never 0.
When this does not work
Empty is an answer. A cursor from another query is a mistake.
| Situation | Status | Code |
|---|---|---|
| No public videos match the query | 200 | empty data |
| The cursor came from another query or freshness | 400 | CURSOR_MISMATCH |
{
"error": {
"code": "CURSOR_MISMATCH",
"message": "The cursor does not belong to this request.",
"requestId": "req_01j8…",
"retryable": false
}
}An empty page bills as an answered request. A cursor is bound to its query and freshness. Change either and start without a cursor.
Read next
More TikTok questions
Send your agent ahead.
Paste the prompt into your agent and it sets everything up. Or come yourself, it takes five minutes.