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.
The example response below is real output from this endpoint, not an illustration. Long lists and long strings are shortened to keep the page readable, and each place that happens is marked. This example took 1.5s.
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 }}