# TikTok video search API

> Videos matching keywords worldwide, with plays, likes, comments and shares.

Canonical page: https://okdata.online/apis/tiktok/videos/search/

- **Endpoint**: `GET /v1/tiktok/videos/search`
- **ID**: `tiktok.videos.search`
- **Price**: $0.002 per call · about 30 videos per page
- **Returns**: a page of about 30 videos (`data.items`, Post objects)
- **Status**: preview
- **Good for**: Content research, Trend research

## Price

One call costs $0.002 and returns one page of about 30 videos. Collecting 1,000 videos takes about 34 calls, $0.068 in total. Each page is a separate call. A call that reached the data source is charged even when it comes back empty, not found or failed; calls stopped before reaching a source are free.

## Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes |  | Keywords, as a person would type them into the platform search box. (e.g. `ai agents`) |
| `sort` | string: relevance / latest / most_liked | no | `relevance` | Result order. |
| `cursor` | string | no |  | Opaque cursor from page.next_cursor of the previous call. Each page is a separate call. |
| `view` | string: brief / compact / standard / full | no | `standard` | How much of each object comes back. brief: IDs, title, the first 100 characters of the text, link, time and the main counts, for scanning a list (then get what you need by ID). compact leaves out empty fields and cuts long text at 500 characters. full adds platform-specific fields under ext. |
| `fields` | string[] | no |  | Fields to keep, by path (author.name), to save tokens. In a query string: comma-separated. |

cursor, view and fields work as described in [Requests](https://okdata.online/docs/requests/).

## Returned fields

Each item is a [Post](https://okdata.online/docs/objects/post/).

| Field | Type | Description |
|---|---|---|
| `id` | string | Post ID on the platform. |
| `url` | string | Link to the post. |
| `type` | string | What kind of post it is. |
| `title` | string \| null | Title, where the platform has one (videos, notes, articles). |
| `text` | string | Caption, body or description as plain text; articles come as Markdown. |
| `lang` | string \| null | Language code, as reported or detected. |
| `published_at` | string \| null | When it was published, ISO 8601 in UTC; null only where the source gives no time (wechat_mp.articles.metrics, wechat_channels.videos.metrics, youtube.channels.videos.list with type=short) or left it out of an answer (youtube.videos.get now and then), then listed in meta.unavailable. Never an empty string. |
| `author` | AccountRef | Who posted it. |
| `metrics` | Metrics | Counts at fetch time; a count the platform hides is null. |
| `images` | string[] \| null | Image URLs for image posts and notes. |
| `hashtags` | string[] \| null | Hashtags or topics, without the # sign. |
| `ext` | object | Platform-specific extras. Only returned with view=full. |

## Request examples

### cURL

```bash
curl -G "https://api.okdata.online/v1/tiktok/videos/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=ai agents'
```

### Python

```python
import os
import requests

resp = requests.get(
    "https://api.okdata.online/v1/tiktok/videos/search",
    headers={"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"},
    params={"query": "ai agents"},
    timeout=60,
)
body = resp.json()
if body["code"] != "ok":
    raise RuntimeError(f"{body['code']}: {body['message']} (charged: {body['charged']})")

for row in body["data"]["items"]:
    print(row["id"], row["metrics"]["likes"], row["text"][:60])
print("cost: $" + body["meta"]["billing"]["amount"])
```

### TypeScript

```ts
const url = new URL('https://api.okdata.online/v1/tiktok/videos/search');
url.searchParams.set('query', "ai agents");

const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.OKDATA_API_KEY}`,
  },
});
const body = await res.json();
if (body.code !== 'ok') throw new Error(`${body.code}: ${body.message}`);

for (const row of body.data.items) {
  console.log(row.id, row.metrics.likes, row.text.slice(0, 60));
}
console.log('cost: $' + body.meta.billing.amount);
```

### MCP

```json
{
  "name": "call",
  "arguments": {
    "capability": "tiktok.videos.search",
    "query": "ai agents"
  }
}
```

Or ask an agent that has the MCP server connected:

> Use TikTok video search and list the five posts with the most likes, with links.

## Response example

```json
{
  "code": "ok",
  "request_id": "0f6c2a8e-4b1d-4e0a-9a51-3c7d2b9e1f20",
  "data": {
    "items": [
      {
        "id": "7305085486984858894",
        "url": "https://www.tiktok.com/@trailkit/video/7305085486984858894",
        "type": "video",
        "title": null,
        "text": "Everything I packed for two nights in the hills #camping #gear",
        "lang": "en",
        "published_at": "2026-11-02T09:30:00Z",
        "author": {
          "id": "6812345678901234567",
          "username": "trailkit",
          "name": "Trail Kit",
          "avatar_url": "https://cdn.example.com/avatar/trailkit.jpg",
          "followers": 182300,
          "verified": true
        },
        "metrics": {
          "views": 1250000,
          "likes": 48200,
          "comments": 1312,
          "shares": 2210,
          "favorites": 9650,
          "reposts": null
        },
        "images": null,
        "hashtags": [
          "camping",
          "gear"
        ]
      }
    ]
  },
  "page": {
    "next_cursor": "c1.k3Vq9TzR0bYw2LmXe8NdPa",
    "cursor_expires_at": "2026-11-12T08:00:00Z",
    "has_more": true,
    "returned": 1
  },
  "warnings": [],
  "meta": {
    "capability": "tiktok.videos.search",
    "result_status": "complete",
    "billing": {
      "amount": "0.002",
      "currency": "USD",
      "balance_after": "9.998"
    },
    "unavailable": {
      "metrics.reposts": "platform"
    },
    "cached": false,
    "replayed": false,
    "fetched_at": "2026-11-11T08:00:00Z"
  }
}
```

## Errors

Errors share one shape: code, request_id, message and message_zh (a fixed sentence per code), charged, retry, retry_after_seconds, param and docs_url, with the specifics in problems. An error from a call that reached the data source (not found, a failure or a timeout of the source) is charged once at this endpoint's price, with charged: true and amount; errors before that, such as bad parameters, are not charged. Only settlement_unknown is unknown until looked up. The full table: https://okdata.online/docs/errors/

## Questions

### How much does the TikTok video search API cost?

One call costs $0.002 and returns one page of about 30 videos. Collecting 1,000 videos takes about 34 calls, $0.068 in total. Each page is a separate call. A call that reached the data source is charged even when it comes back empty, not found or failed; calls stopped before reaching a source are free.

### How do I get the next page?

Pass page.next_cursor from the response back as the cursor parameter. When page.has_more is false there is nothing left. Every page is its own call at $0.002.

### Do I need a TikTok account, cookies or a QR login?

No. You send only your okdata API key. The data is public data from TikTok; nothing is fetched with your own TikTok account.

### Am I charged when a call fails?

Yes, once, when the call reached the data source: an empty answer, a not_found, a failure or a timeout of the source costs one call (one item for per-item endpoints), and the error says charged: true with amount. Calls refused before reaching a source, such as bad parameters or a low balance, cost nothing.

### What if TikTok does not show a field?

The field is null, and meta.unavailable names it with the reason: platform (the platform never shows it) or capability (we cannot fetch it yet).

## More TikTok endpoints

- [TikTok video detail](https://okdata.online/apis/tiktok/videos/get/): $0.002 per call
- [TikTok video comments](https://okdata.online/apis/tiktok/videos/comments/list/): $0.002 per call · about 50 comments per page
- [TikTok account profile](https://okdata.online/apis/tiktok/users/get/): $0.002 per call
- [TikTok Ads Library search](https://okdata.online/apis/tiktok/ads/search/): $0.004 per call · about 12 ads per page
- [TikTok Creative Center top ads](https://okdata.online/apis/tiktok/creative_center/ads/search/): $0.002 per call · about 20 ads per page
- [TikTok Shop product search](https://okdata.online/apis/tiktok/shop/products/search/): $0.004 per call · about 20 products per page
- [TikTok Shop product detail](https://okdata.online/apis/tiktok/shop/products/get/): $0.002 per call
- [TikTok Shop product reviews](https://okdata.online/apis/tiktok/shop/products/reviews/list/): $0.002 per call · about 20 reviews per page
- [TikTok video transcript](https://okdata.online/apis/tiktok/videos/transcript/get/): $0.002 per call
- [TikTok comment replies](https://okdata.online/apis/tiktok/comments/replies/list/): $0.002 per call · about 20 comments per page
- [TikTok account search](https://okdata.online/apis/tiktok/users/search/): $0.002 per call · about 30 accounts per page
- [TikTok account videos](https://okdata.online/apis/tiktok/users/videos/list/): $0.002 per call · about 10 videos per page
- [TikTok Creative Center top ad](https://okdata.online/apis/tiktok/creative_center/ads/get/): $0.002 per call
- [TikTok Shop seller products](https://okdata.online/apis/tiktok/shop/sellers/products/list/): $0.002 per call · about 20 products per page
- [TikTok account followers](https://okdata.online/apis/tiktok/users/followers/list/): $0.002 per call · about 20 accounts per page
- [TikTok hashtag videos](https://okdata.online/apis/tiktok/hashtags/videos/list/): $0.002 per call · about 20 videos per page
- [TikTok account LIVE status](https://okdata.online/apis/tiktok/live/users/get/): $0.002 per call
- [TikTok LIVE shopping bag](https://okdata.online/apis/tiktok/live/rooms/products/list/): $0.002 per call · about 15 products per page
- [TikTok LIVE shopping ranking](https://okdata.online/apis/tiktok/live/streamers/trending/): $0.002 per call · about 99 results per page

## At a glance

- **Short name**: TikTok video search
- **Category**: [Social media](https://okdata.online/categories/social/)
- **Data type**: [Post search API](https://okdata.online/roles/posts-search/)
- **Status**: preview. It may still change; any change is announced beforehand.
- **Price**: $0.002 per call · bad parameters are free
- **Returns**: About 30 videos a page, with a cursor for the next page
- **If a call fails**: Charged once. When a data source fails, the next one is tried. A call that reached a source is charged once even if it fails; bad parameters are free.

## When it is charged

- Data comes back: $0.002 per call
- Bad parameters, too little balance, a paused endpoint: Free

| When | Charge |
|---|---|
| Each further page | A new call: $0.002 |
| Most one call costs | $0.002 |
| An empty answer | $0.002 |
| The data source fails or times out | $0.002 |
| Bad parameters, too little balance, a paused endpoint | Free |
| Resent with the same Idempotency-Key within 24 hours | Free when the kept result comes back |

A call that reached the data source costs $0.002 even when the answer is empty, not found or a failure of the source; a call stopped before that, such as for bad parameters, is free.

Prices from price book 53dd8ce13c359590. [Every price on this platform](https://okdata.online/pricing/tiktok/)

- New accounts get $0.10 of credit, no card needed: 50 calls to this endpoint.
- About 34 calls fetch 1,000 videos: $0.068 in all.

## Known limits

- About 30 videos come back per page; the platform sets the page size, so there is no page-size parameter.
- For the next page, pass `page.next_cursor` back as `cursor`. A cursor stays valid for 24 hours. When `page.has_more` is false there is nothing left.

## Fields by view

The view column is the smallest `view` a field comes back in: `compact` returns only compact fields, `standard` adds the standard ones, `full` returns everything. The default is `standard`.

- `compact`: `id`, `url`, `type`, `title`, `text`, `published_at`, `author`, `metrics`
- `standard`: `lang`, `images`, `hashtags`
- `full`: `ext`

## What this endpoint cannot give

- `metrics.reposts`: the platform does not show it (null, listed in meta.unavailable)

## Common errors on this endpoint

| HTTP | Code | Meaning | Charged | Retry |
|---|---|---|---|---|
| 400 | `invalid_params` | A parameter is missing, has the wrong type or value, or the method is wrong. problems lists each one; param names the first. | no | after a fix |
| 400 | `cursor_mismatch` | The cursor was sent to another endpoint, or with other parameters than the page it came from (view and fields may change). | no | after a fix |
| 401 | `unauthorized` | The key is missing, malformed, revoked, disabled or expired (reason says which when known). | no | no |
| 402 | `insufficient_balance` | The balance (available) cannot cover the most this call could cost (required). | no | after a fix |
| 410 | `cursor_expired` | The cursor is older than the endpoint's cursor lifetime (page.cursor_expires_at said when). | no | no |
| 429 | `rate_limited` | The account sent too many requests this minute (reason: rate) or has too many calls running (reason: concurrency). | no | yes |
| 500 | `settlement_unknown` | The data came back, but the charge could not be confirmed. | unknown until looked up | with the same Idempotency-Key |
| 502 | `upstream_failed` | Every data source for this endpoint failed on this request. If a source billed the attempt, it is charged once at the endpoint's price (charged: true and amount); otherwise nothing is charged. | once, if it reached a data source | yes |
| 503 | `capability_paused` | This endpoint is paused right now; nothing ran. | no | yes |
| 504 | `timeout` | The data did not come back in time. If the request had reached a data source that bills it, it is charged once at the endpoint's price (charged: true and amount); otherwise the hold is released. | once, if it reached a data source | yes |

[All error codes](https://okdata.online/docs/errors/)

## Same data on other platforms

- [Douyin video search](https://okdata.online/apis/douyin/videos/search/): $0.02 per call · about 20 videos per page
- [Xiaohongshu note search](https://okdata.online/apis/xiaohongshu/notes/search/): $0.02 per call · about 20 notes per page
- [Bilibili video search](https://okdata.online/apis/bilibili/videos/search/): $0.002 per call · about 20 videos per page
- [Weibo post search](https://okdata.online/apis/weibo/posts/search/): $0.002 per call · about 10 posts per page
- [X post search](https://okdata.online/apis/x/posts/search/): $0.002 per call · about 20 posts per page
- [YouTube video search](https://okdata.online/apis/youtube/videos/search/): $0.004 per call · about 20 videos per page
- [Reddit post search](https://okdata.online/apis/reddit/posts/search/): $0.004 per call · about 25 posts per page
- [Kuaishou video search](https://okdata.online/apis/kuaishou/videos/search/): $0.02 per call · about 10 videos per page
- [Zhihu search](https://okdata.online/apis/zhihu/posts/search/): $0.002 per call · about 20 posts per page
- [WeChat Channels video search](https://okdata.online/apis/wechat_channels/videos/search/): $0.02 per call · about 10 videos per page
- [WeChat Search articles and videos](https://okdata.online/apis/wechat/posts/search/): $0.02 per call · about 20 posts per page
- [Xigua Video search](https://okdata.online/apis/xigua/videos/search/): $0.002 per call · about 10 videos per page

[Post search API](https://okdata.online/roles/posts-search/)

## Use it in your AI

> Read https://okdata.online/apis/tiktok/videos/search.md, then call this endpoint for me through okdata; my key is in the OKDATA_API_KEY environment variable. Use TikTok video search and list the five posts with the most likes, with links.

## TikTok endpoints by group

- [TikTok Creative Center API](https://okdata.online/apis/tiktok/creative_center/): TikTok Creative Center top ads $0.002, TikTok Creative Center top ad $0.002
- [TikTok Shop API](https://okdata.online/apis/tiktok/shop/): TikTok Shop product search $0.004, TikTok Shop product detail $0.002, TikTok Shop product reviews $0.002, TikTok Shop seller products $0.002

## Answers that use this endpoint

- [Is there an MCP server that lets Cursor search TikTok, Instagram and Reddit?](https://okdata.online/answers/cursor-mcp-tiktok-instagram-reddit/): Yes. Put https://api.okdata.online/mcp in ~/.cursor/mcp.json with your key in an Authorization header, and Cursor's agent can search TikTok videos ($0.002 for about 30), Instagram posts by hashtag ($0.004 a page) and Reddit posts ($0.004 for about 25), then read the comments under them. Only one of the five tools costs money; a 24-call research session across the three platforms comes to $0.068.
- [How do I get the transcript or captions of a TikTok video as text?](https://okdata.online/answers/tiktok-video-transcript-api/): Call TikTok video transcript with the video's link or ID: it returns the whole text and timed segments, taken from the captions TikTok has for the video (mostly auto-generated), for $0.002 a video. Pass lang (en, es, ja) to pick a caption language. A video without captions in that language comes back as not_found, charged the same. TikTok's own Research API has a voice_to_text field, but only approved academic researchers can use it.
- [Do I need residential proxies to scrape Douyin or TikTok, and what do they cost?](https://okdata.online/answers/do-i-need-proxies-for-social-media-scraping/): If you scrape Douyin or TikTok yourself at any real volume, almost certainly yes, because server IPs get blocked quickly and residential traffic is sold by the gigabyte. Through okdata you need no proxy: 1,000 TikTok videos from search cost $0.068, 1,000 Douyin videos $1.00, and 1,000 Douyin comments $0.10.
- [How do I find TikTok creators in a niche with an API?](https://okdata.online/answers/find-tiktok-creators-by-niche/): Search the niche's keywords with TikTok video search ($0.002 per page of about 30 videos), group the videos by creator, then pull each promising creator's followers, total likes and video count with TikTok account profile ($0.002 each). A shortlist built from 10 keywords × 3 pages and 150 profiles costs $0.36.
- [Is it legal to scrape public social media data?](https://okdata.online/answers/is-scraping-public-social-media-data-legal/): Often it can be, but it depends on where you are, how you collect and what you do with the data, so treat this as general information and ask a lawyer about your case. US courts have found that scraping public pages is unlikely to count as hacking, yet contract, copyright and privacy law still apply. A data API such as okdata returns public data only (X search is $0.002 a page), but it does not take the legal responsibility for your use off you.
- [How do I add TikTok and YouTube data as tools in a Node.js agent?](https://okdata.online/answers/node-agent-tiktok-youtube-tools/): Wrap each endpoint in a tool with a zod schema and a fetch call: the model picks the tool, your code calls okdata and returns trimmed JSON. A TikTok search tool costs $0.002 per call for about 30 videos, and a YouTube transcript tool $0.004 per video; nothing runs on your server except the HTTP request.
- [Pay-per-call or subscription: which social data API pricing is cheaper?](https://okdata.online/answers/pay-per-call-vs-subscription-data-api/): Pay-per-call is cheaper whenever your usage is irregular or below what a plan includes; a subscription wins only when you use most of its quota every month. On okdata there is no monthly fee, so a month with 600 Weibo searches costs $1.20 and a quiet month costs nothing. Divide a plan's monthly fee by the per-call price to find the call count where it starts to pay off.
- [How do I call a social media data API from a Python agent with function calling?](https://okdata.online/answers/python-agent-function-calling-social-data/): Describe one search function as a tool, run the HTTP call when the model asks for it, and hand back a trimmed JSON result, errors included. With okdata one key covers every platform: a TikTok search costs $0.002 per call, a Xiaohongshu search $0.02 and a Douyin search $0.02, and a call with bad parameters is refused before it costs anything, so the model can fix the parameter and try again.
- [Is there one API to track a brand across TikTok, YouTube and X?](https://okdata.online/answers/social-listening-api-tiktok-youtube-x/): Yes: okdata searches TikTok ($0.002 a page), YouTube ($0.004 a page) and X ($0.002 a page) with one key, and returns posts in the same shape on all three. A weekly brand sweep of about 120 TikTok videos, 40 YouTube videos with their top comments and 200 X posts costs $0.076.
- [Is there a free trial for a social media data API so I can test before paying?](https://okdata.online/answers/social-media-data-api-free-trial/): Yes. Every new okdata key starts with $0.10 of real balance, so test calls return real data from the platforms. A first test of one Douyin and one Weibo hot list, ten TikTok searches and twenty X profiles costs $0.032. Browsing the catalog, prices and fields costs nothing and needs no key, and calls refused for bad parameters never use the credit.
- [What does it cost to pull 1,000 posts from X, TikTok, Weibo or Xiaohongshu through an API?](https://okdata.online/answers/social-media-posts-cost-per-1000/): Through okdata keyword search, 1,000 posts cost $0.10 on X, $0.068 on TikTok, $0.20 on Weibo and $1.00 on Xiaohongshu. Each call is one page of results ($0.002 for about 20 X posts), and results already carry likes, comment counts and the author, so most jobs need no extra calls.
- [How do I get the videos for a TikTok hashtag through an API?](https://okdata.online/answers/tiktok-hashtag-videos-api/): There is no hashtag feed in the catalog, so search the tag as a keyword with TikTok video search (/v1/tiktok/videos/search) and keep the videos whose hashtags list contains it. Each page of about 30 videos costs $0.002; 300 videos take 10 calls, $0.02.
- [TikTok's Research API is only for academics. What can a company use instead?](https://okdata.online/answers/tiktok-research-api-alternative/): A company that cannot get TikTok Research API access can read the same kind of public data through okdata with just an API key: video search at $0.002 a page of about 30 videos, video detail at $0.002, account profiles at $0.002, and comments at $0.002 a page. There is no application, no university affiliation and no review queue.
- [Is there an API to search TikTok videos by keyword?](https://okdata.online/answers/tiktok-video-search-api/): Yes. TikTok video search (/v1/tiktok/videos/search) takes a keyword and returns a page of about 30 public videos with caption, author, plays, likes, comments and shares for $0.002 a call. 1,000 videos take 34 calls, $0.068 in total, with no TikTok account and no approval process.
- [Is there an MCP server that gives Claude TikTok, YouTube and X data?](https://okdata.online/answers/tiktok-youtube-x-mcp-server/): Yes. Add the okdata MCP server (https://api.okdata.online/mcp) to Claude with your API key, and Claude can search TikTok ($0.002 a page), read YouTube transcripts ($0.004 a video) and search X ($0.002 a page), plus comments, profiles and trends, all with one key and no platform logins. A ten-call research session across the three costs $0.035.
- [TikTokApi keeps throwing EmptyResponseException. Is there a more reliable way to get TikTok data?](https://okdata.online/answers/tiktokapi-emptyresponseexception/): EmptyResponseException means TikTok treated your automated browser session as a bot and sent back nothing. If you only need public data, a hosted API skips the browser, ms_token and proxies: okdata returns a video for $0.002, a profile for $0.002 and a search page of about 30 videos for $0.002, each charged once however many times we retry it behind the scenes.
- [Which TikTok comments API can I use for sentiment analysis?](https://okdata.online/answers/tiktok-comments-api-sentiment-analysis/): Use TikTok video comments (/v1/tiktok/videos/comments/list): $0.002 per call with about 50 comments a page, so 1,000 comments cost $0.04. Each comment has text, likes, reply count, time and author, which is what a sentiment model needs. Find the videos first with TikTok video search at $0.002 a call.
