InsightSocial API
TikTok

TikTok Search Top API reference

Your first 10 calls are free, no card needed. Pricing and FAQ

Get a free API key
Example request
curl "https://api.insightsocial.app/v1/tiktok/search/top?query=dance%20challenge" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"
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= 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.

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

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.

cursor?integer

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

since?string

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.

until?string

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

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.

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

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.

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.

Range1 <= value <= 5
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.

Value in

  • "1"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://api.insightsocial.app/v1/tiktok/search/top?query=string"
{  "success": true,  "platform": "string",  "endpoint": "string",  "schema_version": "2",  "pagination": {    "next_cursor": "string",    "has_more": true,    "page_size": 0,    "stopped_at": "since"  },  "unavailable": [    "string"  ],  "credits_used": 0,  "credits_remaining": 0,  "request_id": "string",  "cached": true,  "idempotent_replay": true,  "charge_reason": "string",  "free_call": true,  "data": {    "items": [      {        "post": {          "id": "string",          "url": "http://example.com",          "kind": "string",          "content": {            "text": "string",            "media_urls": [              "http://example.com"            ],            "thumbnail_url": "http://example.com",            "duration_seconds": 0          },          "author": {            "id": "string",            "username": "string",            "display_name": "string",            "avatar_url": "http://example.com",            "verified": true          },          "engagement": {            "views": 0,            "likes": 0,            "comments": 0,            "shares": 0,            "saves": 0          },          "flags": {            "nsfw": true,            "spoiler": true,            "pinned": true,            "deleted": true,            "likes_hidden": true,            "comments_hidden": true,            "shares_hidden": true,            "views_hidden": true,            "saves_hidden": true          },          "published_at": "2019-08-24T14:15:22Z",          "language": "string",          "ext": {            "property1": null,            "property2": null          }        }      }    ],    "total": 0,    "truncated": true,    "ext": {      "property1": null,      "property2": null    }  }}

Search › Suggestions GET

Returns the autocomplete suggestions TikTok's own search box shows for a partial query, as a list of suggestion rows.

Search › Users GET

Returns TikTok accounts for a search term with username, name, avatar, followers, verification. include=profile adds bio, region, link and category.