> ## Documentation Index > Fetch the complete documentation index at: https://docs.sociavault.com/llms.txt > Use this file to discover all available pages before exploring further. # Search Top Ads > Discover the best-performing TikTok Creative Center ads across regions, industries, and time windows. Filter by keyword, objective, format, and engagement metrics to study what's working in any market. **Credit Cost:** 1 credit per request 💳 **1 credit per request** ## OpenAPI ````yaml GET /v1/scrape/tiktok-ad-library/search openapi: 3.1.0 info: title: SociaVault API version: 1.0.0 description: >- # SociaVault API Documentation The SociaVault API provides comprehensive access to social media data extraction across multiple platforms. ## Features - **Multi-Platform Support**: TikTok, Instagram, YouTube, Facebook, Twitter, Reddit, Threads, and more - **Credit-Based System**: Pay-as-you-go pricing with transparent credit costs - **High Performance**: Fast, reliable data extraction - **Comprehensive Data**: Detailed user profiles, videos, posts, comments, and analytics ## Authentication All API requests require authentication using an API key in the `X-API-Key` header: ```bash X-API-Key: sk_live_your_api_key_here ``` Get your API key from the [SociaVault Dashboard](https://sociavault.com/dashboard). ## Credits Each endpoint consumes credits based on data complexity: - Simple requests (profiles): 1 credit - Complex requests (demographics): 20+ credits - Paginated requests: Credits per page Check your credit balance in the dashboard or via the API. ## Support - **Documentation**: https://docs.sociavault.com - **Email**: support@sociavault.com - **Discord**: https://discord.gg/sociavault contact: name: SociaVault Support email: support@sociavault.com url: https://sociavault.com/support license: name: Commercial url: https://sociavault.com/terms servers: - url: https://api.sociavault.com description: Production API security: - ApiKeyAuth: [] tags: - name: account description: Account management and credit balance externalDocs: description: Learn more url: https://docs.sociavault.com/account - name: tiktok description: Scrape TikTok profiles, videos, and more externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/tiktok - name: tiktok-shop description: Everything about TikTok Shop externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/tiktok-shop - name: instagram description: Gets Instagram profiles, posts, and reels externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/instagram - name: youtube description: Scrape YouTube channels, videos, and more externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/youtube - name: linkedin description: Scrape LinkedIn externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/linkedin - name: facebook description: Get public Facebook profiles and posts externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/facebook - name: facebookAdLibrary description: Scrapes the Facebook (Meta) Ad Library externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/facebookAdLibrary - name: facebookMarketplace description: Search Facebook Marketplace and pull full listing details externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/facebookMarketplace - name: googleAdLibrary description: >- Scrape the Google Ad Transparency Library. *This only gets the public ads. Some ads you need to log in for and sadly we can't get those. Also, since there are so many variations, the return types might not all be 100% the same. externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/googleAdLibrary - name: linkedinAdLibrary description: Search the LinkedIn Ad Library externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/linkedinAdLibrary - name: twitter description: Get Twitter profiles, tweets, followers and more externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/twitter - name: reddit description: Scrape Reddit posts and comments externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/reddit - name: threads description: Get Threads posts externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/threads - name: google description: Scrape Google search results externalDocs: description: Learn more url: https://docs.sociavault.com/platforms/google paths: /v1/scrape/tiktok-ad-library/search: get: tags: - tiktok-ad-library summary: Search Top Ads description: >- Discover the best-performing TikTok Creative Center ads across regions, industries, and time windows. Filter by keyword, objective, format, and engagement metrics to study what's working in any market. **Credit Cost:** 1 credit per request operationId: tiktok_ad_library_Search parameters: - name: region in: query description: Country code. Defaults to US. required: false schema: type: string default: US example: US enum: - DZ - AR - AU - AT - AZ - BH - BD - BY - BE - BO - BR - BG - KH - CA - CL - CO - CR - HR - CY - CZ - DK - DO - EC - EG - EE - FI - FR - DE - GR - GT - JO - HU - ID - IQ - IE - IL - IT - JP - KZ - KE - KW - LV - LB - MY - MX - MA - NL - NZ - NG - 'NO' - OM - PK - PA - PY - PE - PH - PL - PT - PR - QA - LT - RO - SA - RS - SG - SK - SI - ZA - KR - ES - LK - SE - CH - TW - TH - TR - AE - GB - US - UY - VN - name: period in: query description: Time window for Top Ads (in days). required: false schema: type: string example: '30' enum: - '7' - '30' - '180' - name: query in: query description: Optional keyword to search ad titles/content. required: false schema: type: string example: spotify - name: order_by in: query description: Sort metric. Defaults to for_you. required: false schema: type: string default: for_you example: for_you enum: - for_you - impression - play_2s_rate - play_6s_rate - cvr - ctr - like - name: industry in: query description: Industry filter. required: false schema: type: string example: beauty_personal_care enum: - apparel_accessories - appliances - apps - baby_kids_maternity - beauty_personal_care - business_services - ecommerce_non_app - education - financial_services - food_beverage - games - health - home_improvement - household_products - life_services - news_entertainment - pets - sports_outdoor - tech_electronics - travel - vehicle_transportation - name: objective in: query description: Campaign objective filter. required: false schema: type: string example: traffic enum: - app_installs - conversions - lead_generation - product_sales - reach - traffic - video_views - name: duration in: query description: Video duration filter. required: false schema: type: string example: under_10s enum: - under_10s - 10_20s - 20_30s - 30_40s - 40_50s - over_50s - name: likes in: query description: Likes percentile filter. required: false schema: type: string example: top_1_20 enum: - top_1_20 - top_21_40 - top_41_60 - top_61_80 - top_81_100 - name: ad_format in: query description: Ad format filter. required: false schema: type: string example: spark_ads enum: - spark_ads - non_spark_ads - name: ad_language in: query description: Ad language filter. required: false schema: type: string example: en enum: - en - es - ar - vi - th - de - id - pt - fr - ms - nl - ja - it - ro - zh-Hant - ko - name: cursor in: query description: >- Page number to fetch. Use the cursor returned from the previous response, like 3 for page 3. required: false schema: type: integer example: 3 - name: limit in: query description: Number of ads to return, max 50. Defaults to 20. required: false schema: type: integer example: 20 responses: '200': description: >- Successful response containing top ads **Key Response Fields:** - `query`: The search keyword used - `region`: Region code applied to the search - `period`: Time window in days - `ads[].id`: Unique ad ID - `ads[].ad_title`: Ad creative text/caption - `ads[].brand_name`: Brand name (if available) - `ads[].ctr`: Click-through rate - `ads[].like`: Total likes on the ad - `ads[].cost`: Credit cost indicator - `ads[].industry_key`: Industry category identifier - `ads[].objective_key`: Campaign objective (e.g. "campaign_objective_traffic") - `ads[].video_info.duration`: Video length in seconds - `ads[].video_info.cover`: Video cover/thumbnail URL - `ads[].video_info.video_url`: Download URLs by quality (540p, 720p) - `ads[].video_info.width`: Video width in pixels - `ads[].video_info.height`: Video height in pixels - `pagination.has_more`: Whether more pages are available - `pagination.page`: Current page number - `pagination.total_count`: Total number of matching ads - `total`: Total ads returned - `has_more`: Whether more pages exist - `cursor`: Cursor value for the next page (null if last page) content: application/json: example: success: true data: success: true query: shoes region: US period: 30 ads: '0': ad_title: >- HR would like to remind you that what happens at the premiere, stays at the premiere. Office Romance June 5 on @Netflix brand_name: '' cost: 1 ctr: 0.34 favorite: false id: '7645249124891607041' industry_key: label_23108000000 is_search: false like: 1294 objective_key: campaign_objective_traffic video_info: vid: v15044gf0000d8blg3vog65m7i2j3320 duration: 55.843 cover: >- https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068c799-us/owWoFXnfIfGLjgWAuAYQXIeqGAQpGQGYReBQGU~tplv-noop.image?dr=18692&refresh_token=25085a08&x-expires=1781236812&x-signature=cYE54g9ru2lGz4QwxLNrzJR7vao%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v15044gf0000d8blg3vog65m7i2j3320 video_url: 540p: >- https://v16m-default.tiktokcdn.com/4cf48674533ea486264fecb0e62bb0d8/6a2b844c/video/tos/maliva/tos-maliva-ve-0068c799-us/osXAIFIWHpGGG8AGAefjLRXQeYUgUoIRWpQfQ3/?a=0&bti=NTU4QDM1NGA%3D&&bt=511&ft=cApXJCz7ThWHE.t9LGZmo0P&mime_type=video_mp4&rc=M2Q7ZDVpODY8NjhpOjk4ZkBpMzZtbHA5cjZvOzMzaTczNEBeLl9fYl4tXzUxNDNiMC40YSMvMC80MmRzZF9hLS1kMTJzcw%3D%3D&vvpl=1&l=202606120559171BEEA8ABD2CB799CFAAE&btag=e00088000 720p: >- https://v16m-default.tiktokcdn.com/1834a0d6d95854f01ac31c062a0d579e/6a2b844c/video/tos/maliva/tos-maliva-ve-0068c799-us/ocf1SxIUCtBCUXsiEWiwHIRIiEJIEAA26jQqPA/?a=0&bti=NTU4QDM1NGA%3D&&bt=1360&ft=cApXJCz7ThWHE.t9LGZmo0P&mime_type=video_mp4&rc=Z2U2OWRlOzw8aTY4aGY5ZUBpMzZtbHA5cjZvOzMzaTczNEAyMi80YzQ1XzAxX2AyYTA1YSMvMC80MmRzZF9hLS1kMTJzcw%3D%3D&vvpl=1&l=202606120559171BEEA8ABD2CB799CFAAE&btag=e00088000 width: 720 height: 1280 '1': ad_title: >- إعلان لا يفوتكم خصومات 30% ثابت في سكتشرز خصومات سكتشرز تناسب كل العائله Skechers #سكتشرز #عروض #خصومات brand_name: '' cost: 0 ctr: 0.9 favorite: false id: '7639391345481367572' industry_key: label_22111000000 is_search: false like: 861 objective_key: campaign_objective_video_view video_info: vid: v1c044g50000d80tnmvog65kkmu4l21g duration: 46.7 cover: >- https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/oUDDlcQbQBVAiQEeBfRuEQpBgvhGdgE3ISA3Fq~tplv-noop.image?dr=18692&refresh_token=a0b1868e&x-expires=1781236803&x-signature=w%2Bd3QIBeS8eKmuX3vyfWIUc%2BuCE%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v1c044g50000d80tnmvog65kkmu4l21g video_url: 720p: >- https://v16m-default.tiktokcdn.com/2d7e28bd73853680e127bc1be7dc1eb5/6a2b8443/video/tos/alisg/tos-alisg-pve-0037c001/oUb3IQLD1oAliixBA0iiw3BtCAAIWBTEIpfKuO/?a=0&bti=NTU4QDM1NGA%3D&&bt=1983&ft=cApXJCz7ThWHE.t9LGZmo0P&mime_type=video_mp4&rc=NGVoOjw5Ojs5PGQ8PDw4NkBpajU3cG45cnB3OzMzODczNEBjYTRfXjEtNjMxXjEzLWBeYSMuaXJoMmRzay1hLS1kMWBzcw%3D%3D&vvpl=1&l=202606120559171BEEA8ABD2CB799CFAAE&btag=e00088000 width: 576 height: 1024 pagination: has_more: false page: 1 size: 20 total_count: 4 total: 4 has_more: false cursor: null credits_used: 1 '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: User not authenticated '402': description: Payment Required - Insufficient credits content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Insufficient credits required: type: integer example: 1 available: type: integer example: 0 components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: |- API key for authentication. Format: `sk_live_xxxxxxxxxxxxx` Get your API key from the [Dashboard](https://sociavault.com/dashboard). ````