Keyword search
GET
https://scraper.riken.me/v1/tiktok/search/keywordCost: 1 credit per pageLiveErrors are free
Try it
Paste your key under Authorization and send a live request to https://scraper.riken.me. The key stays in this browser tab only (session storage, cleared when the tab closes) and is sent nowhere else. A live request spends credits like any other.
GET
TikTok's Top results for a keyword, one page per call. Send back cursor
for the next page; on the last page has_more is 0 and there is no
cursor.
Cursors are bound to your API key, the query and the region page 1
came from, and expire after 24 hours. Another key or query:
400 invalid_cursor. Older than 24 h (or TikTok expired the session):
400 cursor_expired. Page 1's IP session gone: 409 cursor_exit_gone.
A later page only available from another country: 409 cursor_region_changed.
In every case, start again from page 1 without a cursor. A cursor is an
integer of at most 2^53 - 1.
Region. We search from the US, and from Canada when US capacity is
short. X-Search-Region says which (US or CA); all pages of one
search come from the same region. region=CA searches from Canada only.
Page size is what TikTok's Top tab returns (median 23 on page 1 on 31 Oct 2026). Latency (31 Oct 2026, 90 pages, pages 1 to 3): p50 3.9 s, p95 8.9 s.
Headers
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
x-api-key | string | one of the auth headers | Your API key. If both headers are sent, `x-api-key` wins. | sk_... |
Authorization | string | one of the auth headers | `Authorization: Bearer <key>`, the same key. | Bearer sk_... |
Idempotency-Key | string | no | Any string up to 255 characters. Makes a retry safe for 24 hours; bound to this API key and the request's parameters. | profile-dagestantrainingcamp-2026-11-01 |
Query parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
query | string | yes | The keyword. Trimmed. At most 200 bytes, valid UTF-8. | protein |
cursor | string | no | The `cursor` of the previous page. Absent, empty or `0` means page 1. | 4503599627370495 |
date_posted | all-time | yesterday | this-week | this-month | last-3-months | last-6-months | no | `all-time` or absent. `yesterday`, `this-week`, `this-month`, `last-3-months` and `last-6-months` are `400 unsupported_parameter`; anything else `400 bad_request`. | |
sort_by | relevance | most-liked | date-posted | no | `relevance` or absent. `most-liked` and `date-posted` are `400 unsupported_parameter`; anything else `400 bad_request`. | |
region | string | no | Two letters, or absent. `CA` (any case) searches from Canada only; any other two letters use the default order (US, then Canada). Not two letters is `400 bad_request`. | CA |
Status codes
| Status | Charged | Meaning |
|---|---|---|
| 200 | Charged | One page of results. Charged. |
| 400 | Free | A bad parameter, or a cursor that cannot be used. Free. |
| 401 | Free | Missing, unknown or revoked key. Free. |
| 402 | Free | The key cannot cover this request. needed_credits is the price. Free. |
| 409 | Free | An idempotency conflict, or a cursor whose search session cannot continue. Free. |
| 429 | Free | No capacity to answer within the time limit, or the server is restarting. Free. Wait Retry-After seconds. |
| 500 | Free | Our fault. Free; retry and quote X-Request-Id. |
| 502 | Free | TikTok's answer failed or could not be read (including accounts TikTok withholds from logged-out views). Free. |
| 503 | Free | No search IP can serve now (search_unavailable, Retry-After: 60), or the route is not priced. Free. |
| 504 | Free | No answer within the time limit (180 s; audience 300 s). Free. |
One page of results. Charged.
application/json- response
success*unknowncredits_charged*CreditsAn amount in credits, as an exact JSON decimal (1, 0.002), never a rounded float.
Range
0 <= valuecredits_remaining*CreditsRemainingWhat the key can still spend after this request.
search_item_list*array<>has_more*integerValue in
01cursor?integerThe next page's cursor; absent on the last page. Bound to your key, the query and the region; 24 hours.
Range
1 <= value <= 9007199254740991Example request
# A call can be held open up to 180 s (audience: 300 s). Set a client timeout above that.curl -X GET 'https://scraper.riken.me/v1/tiktok/search/keyword?query=protein&cursor=4503599627370495®ion=CA' \ -H 'Idempotency-Key: profile-dagestantrainingcamp-2026-11-01'Example Response
{ "credits_charged": 1, "credits_remaining": 999, "cursor": 4503599627370495, "has_more": 1, "search_item_list": [ { "aweme_info": { "added_sound_music_info": null, "aigc_info": null, "anchors": null, "anchors_extras": null, "animated_image_info": null, "author": { "avatar_168x168": null, "avatar_300x300": null, "avatar_larger": { "height": null, "uri": null, "url_list": [ "https://c/al.jpg" ], "url_prefix": null, "width": null }, "avatar_medium": { "height": null, "uri": null, "url_list": [ "https://c/am.jpg" ], "url_prefix": null, "width": null }, "avatar_thumb": { "height": null, "uri": null, "url_list": [ "https://c/at.jpg" ], "url_prefix": null, "width": null }, "aweme_count": 2017, "commerce_user_level": null, "custom_verify": null, "enterprise_verify_reason": null, "follower_count": 4100000, "following_count": 74, "hide_search": null, "ins_id": null, "is_star": null, "nickname": "Dave Portnoy", "sec_uid": "MS4wLjABAAAAINC_ElRR", "secret": 0, "short_id": null, "total_favorited": 190400000, "uid": "6659752019493208069", "unique_id": "stoolpresidente", "verification_type": 1, "with_commerce_entry": null }, "author_user_id": 6659752019493208000, "aweme_acl": null, "aweme_id": "7334621391758642478", "aweme_type": null, "banners": null, "behind_the_song_music_ids": null, "behind_the_song_video_music_ids": null, "bodydance_score": null, "branded_content_accounts": null, "c2pa_info": null, "cc_template_info": null, "cha_list": [ { "cha_name": "gym", "cid": "1", "desc": "" } ], "challenge_position": null, "cmt_swt": null, "collect_stat": null, "comment_config": null, "comment_topbar_info": null, "commerce_config_data": null, "commerce_info": null, "content_desc": null, "content_desc_extra": null, "content_model": null, "content_original_type": null, "content_size_type": null, "content_type": null, "cover_labels": null, "create_time": 1707840000, "create_time_utc": "2024-02-13T16:00:00.000Z", "creation_info": null, "desc": "leg day #gym", "desc_language": null, "disable_search_trending_bar": null, "distance": null, "distribute_type": null, "follow_up_item_id_groups": null, "follow_up_publish_from_id": null, "geofencing": null, "geofencing_regions": null, "green_screen_materials": null, "group_id": "7334621391758642478", "group_id_list": null, "has_danmaku": null, "has_promote_entry": null, "has_vs_entry": null, "have_dashboard": null, "hybrid_label": null, "image_infos": null, "interact_permission": null, "interaction_stickers": null, "is_ad": false, "is_ads": false, "is_description_translatable": null, "is_eligible_for_commission": null, "is_hash_tag": null, "is_nff_or_nr": null, "is_on_this_day": null, "is_paid_partnership": null, "is_pgcshow": null, "is_preview": null, "is_relieve": null, "is_text_sticker_translatable": null, "is_title_translatable": null, "is_top": null, "is_vr": null, "item_comment_settings": null, "item_duet": null, "item_react": null, "item_stitch": null, "label_top": null, "label_top_text": null, "long_video": null, "main_arch_common": null, "mask_infos": null, "meme_reg_info": null, "misc_info": null, "muf_comment_info_v2": null, "music": { "author": "Dave Portnoy", "duration": 89, "id_str": "7470969632736709422", "is_original_sound": true, "owner_handle": null, "title": "original sound - stoolpresidente" }, "music_begin_time_in_ms": null, "music_end_time_in_ms": null, "music_selected_from": null, "music_title_style": null, "music_volume": null, "need_trim_step": null, "need_vs_entry": null, "nickname_position": null, "no_selected_music": null, "operator_boost_info": null, "origin_comment_ids": null, "origin_volume": null, "original_client_text": null, "picked_users": null, "playlist_blocked": null, "poi_re_tag_signal": null, "position": null, "prevent_download": null, "products_info": null, "promote_capcut_toggle": null, "promote_icon_text": null, "promote_toast": null, "promote_toast_key": null, "question_list": null, "quick_reply_emojis": null, "rate": null, "reference_tts_voice_ids": null, "reference_voice_filter_ids": null, "region": "US", "risk_infos": null, "search_desc": null, "search_highlight": null, "share_info": null, "share_url": "https://www.tiktok.com/@stoolpresidente/video/7334621391758642478", "shoot_tab_name": null, "shop_product_url": null, "social_interaction_blob": null, "solaria_profile": null, "sort_label": null, "standard_component_info": null, "statistics": { "aweme_id": "7334621391758642478", "collect_count": 274, "comment_count": 152, "digg_count": 18651, "download_count": null, "forward_count": null, "lose_comment_count": null, "lose_count": null, "play_count": 141567, "repost_count": null, "share_count": 237, "whatsapp_share_count": null }, "status": { "allow_comment": null, "allow_share": null, "aweme_id": "7334621391758642478", "is_delete": null, "is_prohibited": null, "private_status": 0, "self_see": null }, "suggest_words": null, "support_danmaku": null, "text_extra": [ { "end": 12, "hashtag_id": "1", "hashtag_name": "gym", "sec_uid": "", "start": 8, "type": 1, "user_id": "" } ], "text_sticker_major_lang": null, "title_language": null, "ttec_suggest_words": null, "tts_voice_ids": null, "uniqid_position": null, "upvote_info": null, "upvote_preload": null, "url": "https://www.tiktok.com/@stoolpresidente/video/7334621391758642478", "used_full_song": null, "user_digged": null, "video": { "CoverTsp": null, "ai_dynamic_cover": null, "ai_dynamic_cover_bak": null, "animated_cover": null, "big_thumbs": null, "bit_rate": null, "bit_rate_audio": null, "cdn_url_expired": null, "cover": { "height": null, "uri": null, "url_list": [ "https://c/1.jpg" ], "url_prefix": null, "width": null }, "download_addr": { "height": null, "uri": null, "url_list": [ "https://c/d.mp4" ], "url_prefix": null, "width": null }, "duration": 89000, "dynamic_cover": { "height": null, "uri": null, "url_list": [ "https://c/3.jpg" ], "url_prefix": null, "width": null }, "has_watermark": null, "height": 1024, "is_bytevc1": null, "is_callback": null, "meta": null, "need_set_token": null, "origin_cover": { "height": null, "uri": null, "url_list": [ "https://c/2.jpg" ], "url_prefix": null, "width": null }, "play_addr": { "height": null, "uri": null, "url_list": [ "https://c/p.mp4" ], "url_prefix": null, "width": null }, "play_addr_bytevc1": null, "play_addr_h264": null, "ratio": "540p", "source_HDR_type": null, "tags": null, "width": 576 }, "video_control": null, "video_labels": null, "video_text": null, "visual_search_info": null, "voice_filter_ids": null, "with_promotional_music": null, "without_watermark": null } } ], "success": true}