tiktok_ad_library_top_ads
TikTok Creative Center Top Ads — one ~20-row leaderboard page, not a library search (flat 2; ~1/ad on the fallback path). Costs 2 credits. Empty results and failures are never charged. Pass cache=true for a free 24h cache hit (default always fresh).
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "tiktok_ad_library_top_ads"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Optional keyword that ranks the one ~20-row leaderboard page — not a library search. Case-insensitive whole-word hits on title/brandName/industry/objective (hair ≠ wheelchair) come first; the rest of TikTok's keyword-ranked page follows as fill (matchedFrom [] on those ads, rankedFill in the envelope). There is no tags field. advertiser.name is often null in the default US market. Envelope candidatesScanned is the pre-filter pool size. For a known advertiser, use /tiktok/ad-details by ad id. | |
| cache | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. | |
| limit | No | Max items to return (default 20, max 20). One Creative Center leaderboard page is ~20 rows; limit only trims that pool — it cannot scan more candidates. Flat 2 credits on the native path; the fallback path ~1 credit per returned ad (min 2). | |
| match | No | Keyword token mode: "any" (default, OR) or "all" (AND). Zero whole-word hits still return TikTok's keyword-ranked page as matchBasis=ranked (literalMatches=0). | |
| fields | No | Optional comma-separated keys to keep on each result row (or on the object for single-item tools), e.g. id,url,publishedAt,engagement. Pagination keys are always kept. Does not change the price. | |
| period | No | Lookback window in days: 7, 30, or 180. Default 30. | |
| compact | No | Default true here: drop signed media URLs (video, image, avatar links and their expiry stamps) to keep the response small. Ids, permalinks, dates, text and metrics stay. On Threads, Facebook, Meta Ad Library and TikTok Shop tools request timings are dropped too. Pass false for the full body. | |
| country | No | Two-letter ISO country code. Default US. Non-ISO codes are a definitive 400 INVALID_COUNTRY (Creative Center used to quietly return an empty leaderboard for them). | |
| orderBy | No | Sort: for_you, likes, ctr, impressions, or cost. Default for_you. | |
| adFormat | No | Optional format filter: spark or non_spark. Served only by the extended fetcher — while it is disabled, adFormat returns 503 filter_unavailable (retryable false, not billed). Omit adFormat for the native leaderboard. | |
| industry | No | Optional industry key or label from Creative Center. | |
| objective | No | Optional campaign objective (e.g. Traffic, Conversion, Reach). |