1. Choosing the Right TikTok Search Endpoint
TikTokAPI.io provides four specialized search endpoints depending on whether you are discovering organic videos, creators, hashtags, or paid commercial creatives:
| Search Target | Endpoint | Filter Parameters | Max Page Size | Credit Cost |
|---|---|---|---|---|
| Organic Videos by Keyword | GET /v1/videos/search | query (or keywords), region, publish_time (0/1/7/30/90/180), sort_by (0=Relevance, 1=Likes, 3=Newest) | 30 videos / call | 2 Credits / video (min 10) |
| Creator Accounts | GET /v1/users/search | query (or keywords), follower_tier (0–4), verified_only (0/1) | 30 users / call | 1 Credit / user (min 10) |
| Hashtag Challenges | GET /v1/hashtags/info + /v1/hashtags/videos | hashtag (e.g. skincare) -> hashtag_id | 30 videos / call | 2 Credits / video (min 10) |
| Commercial Ads (Creative Center) | GET /v1/ads/search | keyword, country_code (US, GB, etc.), period (7/30/180), sort_by (impression/ctr/like) | 20 ads / call | 10 Credits / ad (min 10) |
2. Paginated Keyword Video Search (Python & TypeScript)
When paginating through search results, pass cursor=0 on the first request, then read data.cursor and data.hasMore from each response. Our gateway includes built-in stuck-cursor protection that automatically sets hasMore: false if upstream repeats a cursor.
Search TikTok Videos by Keyword, Region & Time Window (GET /v1/videos/search)
Search US TikTok videos matching 'ai tools' published in the past 7 days, sorted by relevance, with safe multi-page cursor pagination.
curl -sS "https://api.tiktokapi.io/v1/videos/search?query=ai+tools&limit=20&cursor=0®ion=US&publish_time=7&sort_by=0" \
-H "x-api-key: tk_your_api_key_here"3. Filter Parameter Reference (publish_time, sort_by, follower_tier)
Use these exact integer codes to filter video search and creator search results at the API level:
| Endpoint | Parameter | Allowed Values | Meaning |
|---|---|---|---|
| /v1/videos/search | publish_time | 0, 1, 7, 30, 90, 180 | 0 = All time, 1 = Yesterday, 7 = Past 7 days, 30 = Past 30 days, 90 = Past 3 months, 180 = Past 6 months |
| /v1/videos/search | sort_by (or sort_type) | 0, 1, 3 | 0 = Relevance, 1 = Most Liked (digg_count), 3 = Newest first |
| /v1/videos/search | region | ISO 3166-1 alpha-2 | US, GB, CA, DE, FR, JP, KR, BR, MX, ID, VN, etc. |
| /v1/users/search | follower_tier (or follower_count) | 0, 1, 2, 3, 4 | 0 = Any, 1 = 0–1K, 2 = 1K–10K, 3 = 10K–100K, 4 = 100K+ followers |
| /v1/users/search | verified_only (or profile_type) | 0, 1 | 0 = All accounts, 1 = Verified blue-check accounts only |
Frequently Asked Questions
- Does /v1/videos/search return no-watermark video download URLs directly inside the search list?
- Yes. Every item in data.videos[] includes data.videos[i].play (direct no-watermark MP4 stream) plus play_count, digg_count, comment_count, share_count, author, and music_info. You do not need to call /v1/videos/detail for each search result unless you specifically need the 1080p hdplay stream.
- How is credit billing calculated on /v1/videos/search?
- Video search is billed per item returned: 2 Credits per video ($0.20 per 1,000 videos at base rate, or $0.08 per 1,000 videos on Business Monthly), with a 10-Credit minimum per successful call.
- Can I pass either query or keywords as the search parameter?
- Yes. Our gateway accepts both query=... (standardized V1 style) and keywords=... (legacy style), as well as both limit=... and count=....