API referenceTikTok
TikTok top ads
TikTok's Top Ads library, the best-performing public ads.
Spend is not published for any ad, so cost comes back null rather than a
misleading zero; ctr and like_count are the library's real metrics.
Authorization
ApiKeyAuth X-API-Key<token>
Your API key. Sent on every request.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/scrapers/tiktok-top-ads-v4" \ -H "Content-Type: application/json" \ -d '{ "country_code": "US", "period": 7 }'{ "request_id": "req_8f2c1d94e7b0", "success": true, "status": { "code": "OK", "message": "Scrape completed.", "retryable": false }, "data": { "ads": [ { "ad_id": "7669876285700816903", "brand_name": null, "comment_count": null, "cost_level": 2, "countries": null, "ctr": 0.2, "has_summary": null, "has_voice_over": null, "highlight_text": null, "industry_key": "label_24113000000", "is_search_ad": true, "keywords": null, "landing_page": null, "like_count": 361, "objective_key": "campaign_objective_traffic", "objectives": null, "share_count": null, "source": null, "source_key": null, "title": "#Ad Not every decision I make now is about food. As @Moo'd Up keep growing, I need answers fast, and more importantly, I need them to be right, especially when it comes to the numbers behind the business. Intuit Intelligence in @QuickBooks get tailored insights right when I need them so I can move confidently. Check ou… (+19 chars)", "video": { "cover_url": "https://p19-common-sign.tiktokcdn.com/tos-alisg-p-37c799-sg/oMcAwBEM0rDzRPAE9DViFswEfuVDRqIEz8IGe2~tplv-noop.image?dr=18692&refresh_token=14985cc6&x-expires=1787508159&x-signature=4R5Nl0MiILL%2B8C%2FCZxWgxKvY7yc%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my2&VideoID=v15044gf0000d9ocuhnog65n0vni44o0", "duration_seconds": 13.652, "height": 1280, "video_id": "v15044gf0000d9ocuhnog65n0vni44o0", "video_link": "https://v16m-default.tiktokcdn.com/f02675b2f3b5cf9653dbdbd52505258a/6a8b35bf/video/tos/alisg/tos-alisg-ve-37c799-sg/owcQEEfElAc1qGwVDEB9RiAuBeIQF8E0DutMzw/?a=0&bti=NTU4QDM1NGA%3D&&bt=1094&ft=cApXJCz7ThWHyUh1LGZmo0P&mime_type=video_mp4&rc=NDc5NGU6OjwzMzZoaWloO0BpMzdseXE5cmtmPDMzaTczNEAyLV4tMzUuXjAxLTJeYzNfYSNsMWstMmRrcm… (+77 chars)", "video_links_by_quality": { "720p": "https://v16m-default.tiktokcdn.com/f02675b2f3b5cf9653dbdbd52505258a/6a8b35bf/video/tos/alisg/tos-alisg-ve-37c799-sg/owcQEEfElAc1qGwVDEB9RiAuBeIQF8E0DutMzw/?a=0&bti=NTU4QDM1NGA%3D&&bt=1094&ft=cApXJCz7ThWHyUh1LGZmo0P&mime_type=video_mp4&rc=NDc5NGU6OjwzMzZoaWloO0BpMzdseXE5cmtmPDMzaTczNEAyLV4tMzUuXjAxLTJeYzNfYSNsMWstMmRrcm… (+77 chars)" }, "width": 720 } }, { "ad_id": "7670622601458597895", "brand_name": null, "comment_count": null, "cost_level": 1, "countries": null, "ctr": 0.28, "has_summary": null, "has_voice_over": null, "highlight_text": null, "industry_key": "label_23125000000", "is_search_ad": true, "keywords": null, "landing_page": null, "like_count": 1062, "objective_key": "campaign_objective_conversion", "objectives": null, "share_count": null, "source": null, "source_key": null, "title": "Disney Dreamlight Valley: Wishblossom Ranch, the New Expansion AVAILABLE NOW!", "video": { "cover_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oEIjraEIEBgqWFcf6iFUzXNuPJi40DAfDB4NCr~tplv-noop.image?dr=18692&refresh_token=21c2e53f&x-expires=1787508161&x-signature=cNJTx5QN2HCoJ5M7dAWcG0amo4U%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my2&VideoID=v14033g50000d9poh5nog65lvun2tb7g", "duration_seconds": 15.04, "height": 1280, "video_id": "v14033g50000d9poh5nog65lvun2tb7g", "video_link": "https://v16m-default.tiktokcdn.com/affeeab973b2f74f4c3afd15c4499dd4/6a8b35c1/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8e1f0tlwUjRQAIAhqfLbGNGCXNi5Ibz0hgAgD/?a=0&bti=NTU4QDM1NGA%3D&&bt=3809&ft=cApXJCz7ThWHyUh1LGZmo0P&mime_type=video_mp4&rc=OGdpMzZlNmg0Z2g0OzY8OUBpamU1eG85cjhyPDMzODYzNEBjNDYuNjEwNV4xYzVhMTY2YSM0cWtzMmRr… (+79 chars)", "video_links_by_quality": { "1080p": "https://v16m-default.tiktokcdn.com/affeeab973b2f74f4c3afd15c4499dd4/6a8b35c1/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8e1f0tlwUjRQAIAhqfLbGNGCXNi5Ibz0hgAgD/?a=0&bti=NTU4QDM1NGA%3D&&bt=3809&ft=cApXJCz7ThWHyUh1LGZmo0P&mime_type=video_mp4&rc=OGdpMzZlNmg0Z2g0OzY8OUBpamU1eG85cjhyPDMzODYzNEBjNDYuNjEwNV4xYzVhMTY2YSM0cWtzMmRr… (+79 chars)", "360p": "https://v16m-default.tiktokcdn.com/28a57e7e5d158b34e3169235793da9ae/6a8b35c1/video/tos/alisg/tos-alisg-ve-0051c001-sg/oMiWzzUvrAGizBYA6hRJAQJmBa4EpOnvIx4s6/?a=0&bti=NTU4QDM1NGA%3D&&bt=894&ft=cApXJCz7ThWHyUh1LGZmo0P&mime_type=video_mp4&rc=Omc4ODhlOmQ4ZTs8Zzg2aUBpamU1eG85cjhyPDMzODYzNEBgL2FjYTY1Xi0xLmIvNmAvYSM0cWtzMmRrZW… (+77 chars)", "480p": "https://v16m-default.tiktokcdn.com/1504a7c5d9afec008ac6207969967b0b/6a8b35c1/video/tos/alisg/tos-alisg-ve-0051c001-sg/o0bUoe0qEAxhgbmZAQLi5DgG1ej0fUwIDGCrnI/?a=0&bti=NTU4QDM1NGA%3D&&bt=1300&ft=cApXJCz7ThWHyUh1LGZmo0P&mime_type=video_mp4&rc=Njc7ZjU0OGY4PGc5OztlaUBpamU1eG85cjhyPDMzODYzNEAvLzA0XmEyX2IxYjVeMy8vYSM0cWtzMmRr… (+79 chars)", "540p": "https://v16m-default.tiktokcdn.com/75c5fc5142c7a6be087095561b076f86/6a8b35c1/video/tos/alisg/tos-alisg-ve-0051c001-sg/okYvAimDO6BArzRnGa6OEUvIMiWhh6Az04YQ4/?a=0&bti=NTU4QDM1NGA%3D&&bt=1740&ft=cApXJCz7ThWHyUh1LGZmo0P&mime_type=video_mp4&rc=aTU0aWRnZGlnPDozaWg6ZUBpamU1eG85cjhyPDMzODYzNEBfNTMyY18vNjMxYTYtNjBgYSM0cWtzMmRrZ… (+78 chars)", "720p": "https://v16m-default.tiktokcdn.com/0e410988edfb37651eafb4074a0ab542/6a8b35c1/video/tos/alisg/tos-alisg-ve-0051c001-sg/oUxQvOA4EIzJ6v6RWYaiAzBUqYi4AEnAmDhAG/?a=0&bti=NTU4QDM1NGA%3D&&bt=2211&ft=cApXJCz7ThWHyUh1LGZmo0P&mime_type=video_mp4&rc=NDxkZjRmaTw6ZmlmNGk0NkBpamU1eG85cjhyPDMzODYzNEBfMzFeYGAtNWIxMTJfMDUvYSM0cWtzMmRrZ… (+78 chars)" }, "width": 720 } }, "… 15 more items in the full response" ], "cursor": null, "has_more": false, "page": 1, "page_size": 20, "total": 17 }, "error": null, "meta": { "client_id": "client_abc123", "scraper": "tiktok-top-ads-v4", "billable": true, "duration_ms": 620 }}