/v1/tiktok/search/top

GET

Top Search

Search TikTok Top results for videos and photo carousels; keyword search returns videos only. TikTok may return duplicate results.

Credit cost	Default: 1 credit How charges are determined Cost is decided per call, not per endpoint: the same operation can cost different amounts depending on what it returns. A call that fails costs 0 credits. A result served from cache costs 0 credits. `default` is the cost when no rule matches. Rules are evaluated in order and the first whose conditions all hold wins. A `when` condition is one of: `param` (the request parameter is true), `outcome` (the classifier's outcome), `empty` / `nonEmpty` (a response field is empty and absent, or a non-empty array or string), `flag` (a response field is exactly true). A cost of `{ perStartedMinute: n, of: [fields] }` is n x max(1, ceil(seconds / 60)), so even a short result bills at least one minute.
Cache support	Not specified in the published contract.
Pagination	No explicit pagination metadata in the published contract. Consult the parameters and response fields below.

Parameters

Name	Location / required	Schema
`query` Keyword to search for	query / required	`string`
`publish_time` Time Frame TikTok was posted	query / optional	`string` Allowed values `["yesterday","this-week","this-month","last-3-months","last-6-months","all-time"]`
`sort_by` Sort by	query / optional	`string` Allowed values `["relevance","most-liked","date-posted"]`
`region` Two-letter proxy country code, such as US, GB, or FR. May help access country-restricted posts; does not filter posts by origin.	query / optional	`string`
`trim` Set to true to get a trimmed response	query / optional	`boolean`
`cursor` Cursor to get more videos. Get 'cursor' from previous response.	query / optional	`number`

Request examples

Replace placeholder values and supply your own API key. For operations with a request body, populate the body using the schema above.

cURL

curl --request GET 'https://api.fetchproof.com/v1/tiktok/search/top?query=YOUR_QUERY' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/tiktok/search/top?query=YOUR_QUERY", {
  method: 'GET',
  headers: { 'x-api-key': process.env.FETCHPROOF_API_KEY }
});
console.log(await response.text());

Python

import os
import requests

response = requests.get("https://api.fetchproof.com/v1/tiktok/search/top?query=YOUR_QUERY",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]})
print(response.text)

Responses

200Success. Envelope: success / credits_remaining / credits_charged.

application/json

object

successrequired

boolean

credits_remainingrequired

integer

credits_chargedrequired

integer

itemsrequired

array

Array items

object

idrequired

string

descrequired

string

content_typeoptional

string

create_timerequired

string

{
  "format": "date-time"
}

desc_languagerequired

string

regionrequired

string

is_toprequired

integer

statisticsrequired

object

aweme_idrequired

string

collect_countrequired

integer

comment_countrequired

integer

digg_countrequired

integer

download_countrequired

integer

forward_countrequired

integer

lose_comment_countrequired

integer

lose_countrequired

integer

play_countrequired

integer

repost_countrequired

integer

share_countrequired

integer

whatsapp_share_countrequired

integer

videorequired

object

ai_dynamic_coverrequired

object

data_sizeoptional

integer

heightoptional

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthoptional

integer

ai_dynamic_cover_bakrequired

object

data_sizeoptional

integer

heightoptional

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthoptional

integer

big_thumbsrequired

array

Array items

object

durationrequired

number

fextrequired

string

img_numrequired

integer

img_urisrequired

array

Array items

string

img_urlrequired

string

img_urlsrequired

array

Array items

string

img_x_lenrequired

integer

img_x_sizerequired

integer

img_y_lenrequired

integer

img_y_sizerequired

integer

intervalrequired

integer

urirequired

string

bit_raterequired

array

Array items

object

HDR_bitrequired

string

HDR_typerequired

string

bit_raterequired

integer

dub_infosrequired

null

fid_profile_labelsrequired

string

fpsrequired

integer

gear_namerequired

string

is_bytevc1required

integer

play_addrrequired

object

data_sizerequired

integer

file_csrequired

string

file_hashrequired

string

heightrequired

integer

urirequired

string

url_keyrequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

quality_typerequired

integer

video_extrarequired

string

bit_rate_audiorequired

array

cdn_url_expiredrequired

integer

cla_inforequired

object

caption_infosrequired

array

Array items

object

caption_formatrequired

string

caption_lengthrequired

integer

cla_subtitle_idrequired

integer

complaint_idrequired

integer

expirerequired

integer

is_auto_generatedrequired

boolean

is_original_captionrequired

boolean

langrequired

string

language_coderequired

string

language_idrequired

integer

source_tagrequired

string

sub_idrequired

integer

sub_versionrequired

string

subtitle_typerequired

integer

translation_typerequired

integer

translator_idrequired

integer

urlrequired

string

url_listrequired

array

Array items

string

variantrequired

string

captions_typerequired

integer

creator_edited_caption_idrequired

integer

enable_auto_captionrequired

integer

has_original_audiorequired

integer

hide_original_captionrequired

boolean

is_author_dubbing_qualifiedrequired

boolean

no_caption_reasonrequired

integer

no_caption_reason_v2required

integer

vertical_positionsrequired

null

show_asr_edit_guide_banneroptional

boolean

original_language_infooptional

object

can_translate_realtimerequired

boolean

can_translate_realtime_skip_translation_lang_checkrequired

boolean

first_subtitle_timerequired

integer

is_burnin_captionrequired

boolean

langrequired

string

language_coderequired

string

language_idrequired

integer

original_caption_typerequired

integer

coverrequired

object

data_sizerequired

integer

heightrequired

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

download_addroptional

object

heightrequired

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

data_sizeoptional

integer

file_csoptional

string

durationrequired

integer

dynamic_coverrequired

object

data_sizerequired

integer

heightrequired

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

has_watermarkrequired

boolean

heightrequired

integer

is_bytevc1required

integer

is_callbackrequired

boolean

metarequired

string

need_set_tokenrequired

boolean

origin_coverrequired

object

data_sizerequired

integer

heightrequired

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

play_addrrequired

object

heightrequired

integer

urirequired

string

url_keyrequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

data_sizeoptional

integer

file_csoptional

string

file_hashoptional

string

ratiorequired

string

tagsrequired

null

widthrequired

integer

CoverTspoptional

schema

anyOf

number

anyOf

schema

anyOf

schema

anyOf

schema

anyOf

integer

anyOf

number

anyOf

integer

anyOf

integer

animated_coveroptional

object

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

cover_is_customoptional

boolean

did_profile_labelsoptional

string

download_no_watermark_addroptional

object

data_sizerequired

integer

file_csrequired

string

file_hashrequired

string

heightrequired

integer

urirequired

string

url_keyrequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

is_long_videooptional

integer

play_addr_bytevc1optional

object

data_sizerequired

integer

file_csrequired

string

file_hashrequired

string

heightrequired

integer

urirequired

string

url_keyrequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

play_addr_h264optional

object

data_sizerequired

integer

file_csrequired

string

file_hashrequired

string

heightrequired

integer

urirequired

string

url_keyrequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

source_HDR_typeoptional

integer

vid_profile_labelsoptional

string

video_modeloptional

string

cover_rgboptional

string

tagoptional

object

background_colorrequired

string

en_titlerequired

string

enable_lower_tagrequired

boolean

font_colorrequired

string

opacityrequired

integer

titlerequired

string

typerequired

string

misc_download_addrsoptional

string

authorrequired

object

accept_private_policyrequired

boolean

account_labelsrequired

null

ad_cover_urlrequired

null

advance_feature_item_orderrequired

null

advanced_feature_inforequired

null

authority_statusrequired

integer

avatar_168x168required

object

heightrequired

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

data_sizeoptional

integer

avatar_300x300required

object

heightrequired

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

data_sizeoptional

integer

avatar_largerrequired

object

heightrequired

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

data_sizeoptional

integer

avatar_mediumrequired

object

heightrequired

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

data_sizeoptional

integer

avatar_thumbrequired

object

heightrequired

integer

urirequired

string

url_listrequired

array

Array items

string

url_prefixrequired

null

widthrequired

integer

data_sizeoptional

integer

avatar_urirequired

string

aweme_countrequired

integer

bold_fieldsrequired

null

can_message_follow_status_listrequired

array

Array items

integer

can_set_geofencingrequired

null

cha_listrequired

null

comment_filter_statusrequired

integer

comment_settingrequired

integer

commerce_user_levelrequired

integer

cover_urlrequired

null

custom_verifyrequired

string

cv_levelrequired

string

download_prompt_tsrequired

integer

enabled_filter_all_commentsrequired

boolean

enterprise_verify_reasonrequired

string

eventsrequired

null

fake_data_inforequired

object

fb_expire_timerequired

integer

follow_statusrequired

integer

follower_countrequired

integer

follower_statusrequired

integer

followers_detailrequired

null

following_countrequired

integer

friends_statusrequired

integer

geofencingrequired

null

hide_searchrequired

boolean

homepage_bottom_toastrequired

null

ins_idrequired

string

is_ad_fakerequired

boolean

is_blockrequired

boolean

is_discipline_memberrequired

boolean

is_muterequired

integer

is_mute_livesrequired

integer

is_mute_non_story_postrequired

integer

is_mute_storyrequired

integer

is_starrequired

boolean

item_listrequired

null

live_agreementrequired

integer

live_commercerequired

boolean

live_verifyrequired

integer

mention_statusrequired

integer

mutual_relation_avatarsrequired

null

name_fieldrequired

string

need_pointsrequired

null

need_recommendrequired

integer

nicknamerequired

string

platform_sync_inforequired

null

prevent_downloadrequired

boolean

relative_usersrequired

null

reply_with_video_flagrequired

integer

room_idrequired

integer

search_highlightrequired

null

search_user_descrequired

string

search_user_namerequired

string

sec_uidrequired

string

secretrequired

integer

shield_comment_noticerequired

integer

shield_digg_noticerequired

integer

shield_edit_field_inforequired

null

shield_follow_noticerequired

integer

short_idrequired

string

show_image_bubblerequired

boolean

special_accountrequired

object

special_account_listrequired

null

special_lockrequired

integer

statusrequired

integer

stitch_settingrequired

integer

story_statusrequired

integer

total_favoritedrequired

integer

type_labelrequired

null

uidrequired

string

unique_idrequired

string

user_canceledrequired

boolean

user_moderequired

integer

user_now_pack_inforequired

object

user_periodrequired

integer

user_profile_guiderequired

null

user_raterequired

integer

user_spark_inforequired

object

user_tagsrequired

null

verification_typerequired

integer

verify_inforequired

string

video_iconrequired

object

heightrequired

integer

urirequired

string

url_listrequired

array

url_prefixrequired

null

widthrequired

integer

white_cover_urlrequired

null

with_commerce_entryrequired

boolean

with_shop_entryrequired

boolean

is_mute_thoughtoptional

integer

user_all_story_metadataoptional

object

post_type_to_countsrequired

array

Array items

object

countrequired

integer

post_typerequired

integer

story_lite_metadatarequired

array

Array items

object

audience_scoperequired

integer

expire_atrequired

integer

item_idrequired

integer

post_typerequired

integer

viewedrequired

boolean

aweme_typeoptional

integer

is_sub_onlyoptional

boolean

user_story_change_timerequired

integer

imagesoptional

array

Array items

string

musicrequired

object

authorrequired

string

durationrequired

integer

idrequired

integer

titlerequired

string

play_urlrequired

string

matched_songrequired

object

authoroptional

string

idoptional

string

titleoptional

string

is_eligible_for_commissionrequired

boolean

is_paid_partnershiprequired

boolean

is_adrequired

boolean

urlrequired

string

shop_product_urlrequired

null

cursorrequired

integer

401Invalid or missing x-api-key

402No credits remaining

403Upstream denied (age gate, audience controls)

404Resource or endpoint not found

429Rate limited