InsightSocial API
TikTok

Search › Top

GET
/v1/tiktok/search/top

Returns the videos TikTok ranks highest for a keyword on its Top tab, each with caption, author, engagement counts, a music id, and post.ext.region (the country the video is registered to).

Use it for TikTok's own relevance ranking. region= only sets the proxy; filter on post.ext.region for one country. search/users returns accounts, which this endpoint does not include.

20 credits per call.

Re-running the exact same call within 1h is free.

Paginates by cursor — see Pagination.

Authorization

apiKey
x-api-key<token>

Your key from the dashboard. It starts with isk_.

In: header

Query Parameters

query*string

Search keyword or phrase

publish_time?string

Time Frame TikTok was posted

Value in

  • "yesterday"
  • "this-week"
  • "this-month"
  • "last-3-months"
  • "last-6-months"
  • "all-time"
sort_by?string

Sort by

Value in

  • "relevance"
  • "most-liked"
  • "date-posted"
region?string

Sets the proxy country (ISO 3166-1 alpha-2). It does not filter the page to that country. Each row already carries post.ext.region, the country the video is registered to; filter on that leaf when you need only one country.

cursor?integer

Cursor to get more videos. Get 'cursor' from previous response.

min_views?integer

Keep only rows with at least this many views (post.engagement.views). A row whose view count is unknown is discarded, so every returned row meets the floor. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; data.walk.discarded counts what was removed and why.

Range0 <= value
max_age_days?integer

Keep only rows published within this many days (post.published_at), 1 to 3650. A row with no date is discarded. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; data.walk.discarded counts what was removed and why.

Range1 <= value <= 3650
country?string

Comma-separated two-letter ISO 3166-1 codes, for example US,GB. Keep only videos TikTok registers to one of these countries (post.ext.region); a row with no country is discarded. This filters rows; it does not change where the search runs (that is region). Filtering runs on our side after each page is fetched, so every page walked is billed as usual; data.walk.discarded counts what was removed and why.

exclude_country?string

Comma-separated two-letter ISO 3166-1 codes, for example IN. Discard videos TikTok registers to any of these countries (post.ext.region); a row with no country is kept. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; data.walk.discarded counts what was removed and why.

sort_rows?"views"

views: return the kept rows ordered by view count, highest first, across every page walked. Rows without a view count go last.

Value in

  • "views"
max_pages?integer

1 to 5 (default 1). Walk up to this many pages in one call and return the rows from all of them (after any filter). Each page walked is billed as one call to this endpoint; the whole walk counts once against your rate limit. The walk stops early at the last page, or when the request's time budget runs low; data.walk.stopped says why (end, max_pages, time_budget, page_error) and data.next_cursor continues from where it stopped.

Range1 <= value <= 5
seen?string

An id you choose (1 to 64 letters, digits, ., _ or -). Rows your account already received under the same seen id are removed from the page, and the page price falls with the share of repeats: page credits x new rows / rows on the page, rounded up, so a page of nothing but repeats is free. Use one id across a set of related searches; data.walk.repeats counts what was removed.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/tiktok/search/top?query=string"
{  "success": true,  "platform": "instagram",  "endpoint": "/v1/instagram/profile/posts",  "data": {    "items": [      "…"    ],    "dropped": 0  },  "pagination": {    "next_cursor": "is2.eyJwIjoyfQ",    "has_more": true,    "page_size": 12  },  "credits_used": 20,  "credits_remaining": 9980,  "request_id": "req_1a2b3c4d5e6f",  "cached": false,  "idempotent_replay": false,  "charge_reason": "miss",  "free_call": false}

Search › Suggestions GET

Returns the autocomplete suggestions TikTok's own search box shows for a partial query, as a list of suggestion rows. Use it for keyword research, or to expand a seed term before running search or search/top. **20 credits** per call. Re-running the exact same call within 1h is free.

Search › Users GET

Returns TikTok accounts for a search term with username, name, avatar, followers, verification. include=profile adds bio, region, link and category. Use it to find accounts by name or topic. Add country=KR (or US, DE, …) when you need creators in one country. The video searches, search and search/top, give you posts rather than accounts. **Metered: 20–2000 credits.** We reserve the ceiling when the call starts and charge what it actually used when it finishes. Re-running the exact same call within 1h is free. Paginates by `cursor` — see [Pagination](/docs/pagination).