search_videos
Search for short-form videos by keyword across TikTok or Instagram. Returns up to 20 videos ranked by engagement, with view counts, likes, shares, comments, hashtags, author info, and URLs. Use when the user asks to find videos about a topic or keyword. Supports optional filters for niche, minimum views, recency window, and region. Pass product_id to check which videos link a specific TikTok Shop product: linkage is exact_product_link only when the video carries that product link; keyword_match videos are NOT verified for that product, and evidence_summary.product_linkage.status is VIDEO_LINKAGE_UNVERIFIED when none link it. Region counts as verified only from the provider-reported video region; otherwise it is unknown. View counts are cumulative and do not show current acceleration.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "search_videos"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max videos to return after filtering. Default 12, max 20. | |
| niche | No | Optional — only return videos whose description contains niche-related tokens. Loose niche strings work ("fitness", "Beauty & Skincare"). | |
| query | Yes | Free-text search term. Examples: "morning routine", "iphone case", "passive income". | |
| region | No | ISO country code (US, GB, BR, PH, JP, etc.). Note: corpus coverage varies by region — small regions may return zero results and a degraded quality flag. | |
| window | No | Recency filter. Maps to the closest ScrapeCreators date bucket AND applies a client-side cutoff for defense-in-depth. | |
| platform | No | Which platform to search. "tiktok" (default) hits ScrapeCreators TikTok keyword search. "instagram" (2026-07-06) hits Instagram Reels search — note IG upstream ignores region/date_posted params, so region enforcement is client-side only (region_verified_count in the response tells you how many results verifiably matched). | |
| min_views | No | Optional view-count floor. Default 0. | |
| product_id | No | Optional TikTok Shop product id. Videos that link this exact product are labelled exact_product_link and listed first; all others stay keyword_match (not verified for this product). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| videos | No | ||
| applied | No | Echo of the filters actually applied — useful for debugging when results look surprising | |
| quality | No | ||
| from_payg | No | ||
| filtered_count | No | Videos returned after filtering + cap | |
| upstream_count | No | Videos returned by upstream before any filtering | |
| evidence_summary | No | Unique creators, creator concentration, posted-date range, duplicates removed, region evidence counts and product_linkage {status: VERIFIED | VIDEO_LINKAGE_UNVERIFIED | NOT_REQUESTED}. | |
| credits_remaining | No | Credits remaining after this call | |
| from_subscription | No |