# How do I search TikTok videos by keyword?

TikTok. Checked September 2026.

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.

## GET /v1/tiktok/search/posts?q=…

```bash
curl "https://api.openhandle.dev/v1/tiktok/search/posts?q=synthetic" \
  -H "Authorization: Bearer $OPENHANDLE_API_KEY"
```

```ts
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();
}
```

200 OK:

```json
{
  "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` |

```json
{
  "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.

## Related

- [How do I get trending TikTok hashtags and sounds?](https://openhandle.dev/questions/how-do-i-get-trending-tiktok-hashtags-and-sounds): What TikTok is pushing now, and how to measure it.
- [Pagination](https://openhandle.dev/docs/concepts/pagination): Opaque cursors, one page per request.
- [TikTok API](https://openhandle.dev/apis/tiktok): Every TikTok endpoint with examples.