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= localises the request but does not filter; filter on post.ext.region for one country. search/users returns accounts, which this endpoint does not include.

10 credits per call.

Paginates by cursor: see Pagination.

get/v1/tiktok/search/top

Request

  • Base URL: https://api.insightsocial.app
  • URL: https://api.insightsocial.app/v1/tiktok/search/top
  • Auth: API key in header x-api-key

Query parameters

querystring required
Example:dance challenge

Search keyword or phrase

publish_time'yesterday' | 'this-week' | 'this-month' | 'last-3-months' | 'last-6-months' | 'all-time'

Time Frame TikTok was posted

sort_by'relevance' | 'most-liked' | 'date-posted'

Sort by

regionstring

Two-letter country code (ISO 3166-1 alpha-2) that localises the results. 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.

cursorinteger

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

sincestring

Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following next_cursor, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept.

untilstring

Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept.

min_viewsinteger

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.

max_age_daysinteger

Keep only rows published within this many days (post.published_at), 1 to 3650. A row with no date is discarded.

countrystring

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).

exclude_countrystring

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.

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.

max_pagesinteger

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.

dry_run'1'

Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.

Response

Success.

successtrue required
platformstring required
endpointstring required
schema_version'2' required
unavailablestring[] required
credits_usedinteger required
credits_remaininginteger required
request_idstring required
cachedboolean required
idempotent_replayboolean required
charge_reasonstring required
free_callboolean required

Changes

No recorded changes to this operation across all 1 revision of this API.