# TikTok Ad Library - Free To Use (`dz_omar/tiktok-ad-library-scraper`) Actor Scrape ads from the TikTok Ad Library by keyword, advertiser name, or URL. Export advertiser, creative type, first/last shown dates, audience size, video/image creatives, and download media files permanently. Full targeting data (regions, age, gender) on demand. No login required. - **URL**: https://apify.com/dz\_omar/tiktok-ad-library-scraper.md - **Developed by:** [FlowExtract API](https://apify.com/dz_omar) (community) - **Categories:** Social media, Automation, Developer tools - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 🔍 TikTok Ad Library Scraper Export TikTok ads by keyword, advertiser, or URL > **Formula:** `Scrapes TikTok ads` + `from the TikTok Ad Library (library.tiktok.com)` + `as clean, structured JSON` **[TikTok Ad Library Scraper](https://apify.com/dz_omar/tiktok-ad-library-scraper?fpr=smcx63)** extracts ads from the official TikTok Ad Library search by keyword, by advertiser name, or paste a library URL directly, and get back advertiser, creative type, shown dates, estimated audience, video and image creatives, and (optionally) full targeting data. No login, no cookies, no browser automation. Perfect for **competitive ad researchers**, **performance marketers**, and **agencies** who need TikTok ad creative and targeting intelligence without manually clicking through the Ad Library. https://www.youtube.com/watch?v=DUMMY_VIDEO_ID --- ### Why scrape the TikTok Ad Library? The TikTok Ad Library is TikTok's public DSA transparency portal, holding roughly one year of ads served across the EU/EEA. It exposes the actual creatives, the advertiser behind them, how long each ad ran, and per ad the age, gender, and regional impression breakdown. That is competitor intelligence you would otherwise pay a SaaS subscription for. Here are some of the most common use cases: - **Competitor ad monitoring**: Track every ad a rival advertiser is running, with first/last shown dates. - **Creative research**: Pull the actual video and image creatives competitors use to model your own. - **Targeting intelligence**: See which countries, age bands, and genders an advertiser targets (with Fetch Ad Detail). - **Market & trend analysis**: Search a keyword across all regions to map who is advertising in a category. - **Ad compliance & due diligence**: Capture ad copy, audit status, and rejection reasons for a brand. --- ### What data can the TikTok Ad Library Scraper extract? #### 🏷️ Ad Identity - `id` Unique TikTok ad identifier - `name` Advertiser display name - `type` Creative format (`video` or `image`) - `audit_status` TikTok moderation status #### 📅 Timeline - `first_shown_date` First date the ad ran (Unix ms, UTC) - `last_shown_date` Most recent date the ad ran (Unix ms, UTC) #### 📊 Reach - `estimated_audience` Bucketed audience size (e.g. `0-1K`, `1K-10K`) #### 🎬 Creatives - `videos` Playable signed video URL + cover image - `image_urls` Image creative URLs - `video_download_url` / `cover_download_url` / `image_download_urls` permanent re-hosted links, present only when **Download Media** is enabled (originals are always kept alongside) #### 🎯 Full Targeting *(only when Fetch Ad Detail is enabled)* - Creative title & advertising objective - Advertiser registry location & business ID - Target audience size and targeted countries - Per-region impressions with age (13-17 … 55+) and gender breakdowns #### 🔖 Provenance - `region`, `sort`, `source_url`, `_source` which search produced the record --- ### ⚙️ How to use the TikTok Ad Library Scraper You provide **URLs**, **keyword filters**, or both. Each URL and each keyword counts as one input item. > **Total results = (number of URLs + number of keywords) × Maximum Results.** > Example: 5 URLs + 6 keywords = 11 inputs. At 16 Maximum Results → 11 × 16 = **176 ads** maximum. #### Input Options ##### Start URLs (Array) Paste full `library.tiktok.com/ads` URLs copied from your browser. Region, dates, sort order, and advertiser filters are read directly from the URL no extra config. | Input value | What it extracts | |---|---| | `https://library.tiktok.com/ads?region=DE&adv_name=nike` | Ads matching "nike" in Germany | | `https://library.tiktok.com/ads?region=all&adv_name=...&query_type=2&adv_biz_ids=...` | A specific advertiser's ads, all regions | ```json { "startUrls": [ { "url": "https://library.tiktok.com/ads?region=DE&adv_name=nike&sort_type=last_shown_date,desc" } ] } ```` ##### Keyword Filters (Array of objects) Build searches manually. Each entry runs independently with its own region, date range, and sort order. - **`query`** The keyword or advertiser name. - **`searchAsAdvertiser`** *(boolean, default `false`)* Off: match the text against ad content (TikTok's "Search this exact phrase"). On: treat the text as an advertiser name and return that advertiser's ads (TikTok's "Advertiser name"). - **`region`** One target country (or `all` for EU/EEA). The API processes one region per search. - **`dateFrom` / `dateTo`** Date range. See the date window note below. - **`sortOrder`** `newest`, `oldest`, `created`, `created-asc`, `popular`, `unpopular`. ```json { "keywords": [ { "query": "summer sale", "region": "DE", "sortOrder": "newest" }, { "query": "Apify Technologies s.r.o.", "searchAsAdvertiser": true, "region": "AT" } ], "maxResults": 10 } ``` ##### `maxResults` (Integer) - **Default**: `10` - Maximum ads collected **per URL and per keyword**. Set to `0` to collect everything the API returns (up to TikTok's hard cap of 1,000 per query). Start with `10` to test. ##### `fetchAdDetail` (Boolean) - **Default**: `false` - When on, the scraper makes one extra request per ad to collect full advertiser, creative, and targeting detail. **This is slower** one additional request per ad. ##### `downloadMedia` (Boolean) - **Default**: `false` - When on, each ad's video and images are downloaded to permanent storage and the links are added to the output (`video_download_url`, `cover_download_url`, `image_download_urls`). TikTok's own media links are signed and expire after a few hours; this re-hosts them so they stay accessible. - Media is downloaded by the **[Universal Downloader](https://apify.com/dz_omar/universal-downloader?fpr=smcx63)** actor and saved to **your** account's storage (free accounts: files expire in ~7 days; paid accounts: retained). > ⏱️ **Performance note both options add time.** > `fetchAdDetail` adds one request per ad. `downloadMedia` adds a separate download per ad (a few seconds each). Each one alone makes a run noticeably slower; **enabling both together compounds the cost** for large result counts (e.g. 1,000 ads) expect a substantially longer run. If you only need metadata, leave both off. Turn them on when you specifically need the full detail and/or permanent media files. #### 📆 The date window (important) The TikTok Ad Library only retains about **one year** of "last shown date" history, and the earliest selectable day slides forward daily. This scraper handles that automatically: - **No dates given** → defaults to roughly the last year (today back to ~364 days). - **Start date too old** → clamped up to the earliest available day, with a warning. The run continues. - **`dateFrom` after `dateTo`** → the entry is rejected with a clear message (dates are reversed). - **Entire range older than ~1 year** → the entry is rejected (nothing to scrape there). *** ### 💰 Pricing > 🎉 **This Actor is currently FREE to use.** You only pay Apify's standard platform usage for the run. There are no per-result charges at this time. Pricing may change in the future. Any change will be shown transparently here and in the Apify Store before you run. *** ### 📊 Sample Output **Without `fetchAdDetail` (`details` is null):** ```json { "id": "1866984139925698", "name": "nexxtstyyle", "type": "video", "audit_status": "1", "first_shown_date": 1780495093000, "last_shown_date": 1780495093000, "estimated_audience": "0-1K", "videos": [ { "video_url": "https://library.tiktok.com/api/v1/cdn/.../video.mp4", "cover_img": "https://p19-common-sign.tiktokcdn.com/.../cover.jpeg" } ], "image_urls": [], "details": null, "region": "DE", "sort": "last_shown_date,desc", "source_url": "URL: https://library.tiktok.com/ads?region=DE&adv_name=nike&sort_type=last_shown_date,desc", "_source": "tiktok_ad_library_scraper" } ``` **With `fetchAdDetail` (`details` populated truncated):** ```json { "id": "1866984139925698", "name": "nexxtstyyle", "type": "video", "estimated_audience": "0-1K", "videos": [ { "video_url": "...", "cover_img": "..." } ], "details": { "ad": { "title": "Nike☀️🔝 #nike #summer", "advertising_objective": "Reach", "estimated_audience": "1K-10K" }, "advertiser": { "name": "Nextstyleee", "adv_biz_ids": "7555084503564304385", "registry_location": "Emirates" }, "targeting": { "target_audience_size": "23.6M-28.8M", "countries": ["ES", "FR", "IT", "DE", "BE"], "location": { "total_region": 5, "data": [ { "region": "ES", "impressions": "2K", "breakdowns": [ { "age": "18-24", "gender": "FEMALE", "impressions": "0-1K" } ] } ] } } }, "region": "DE", "source_url": "URL: https://library.tiktok.com/ads?region=DE&adv_name=nike", "_source": "tiktok_ad_library_scraper" } ``` **With `downloadMedia` (permanent links added alongside originals):** ```json { "id": "1866996966152193", "name": "nikesk87", "type": "video", "videos": [ { "video_url": "https://library.tiktok.com/api/v1/cdn/.../video.mp4?...", "cover_img": "https://p16-common-sign.tiktokcdn.com/.../cover.image?...", "video_download_url": "https://api.apify.com/v2/key-value-stores//records/video-...mp4?signature=...", "cover_download_url": "https://api.apify.com/v2/key-value-stores//records/image-...image?signature=..." } ], "image_urls": [], "image_download_urls": [], "region": "DE", "_source": "tiktok_ad_library_scraper" } ``` The originals (`video_url`, `cover_img`, `image_urls`) are always kept; the `*_download_url` fields are added only when Download Media is on. *** ### ❓ Frequently Asked Questions **Do I need a TikTok account to use this Actor?** No. The TikTok Ad Library is a public transparency portal. This scraper requires no login, cookies, or credentials. **How far back can I search?** About one year. The TikTok Ad Library retains roughly 365 days of "last shown date" history, and the window slides forward daily. Dates older than that are automatically clamped or skipped with a clear message. **Can I scrape multiple keywords and URLs in one run?** Yes. Provide any mix of URLs and keyword filters they are processed in the same run (URLs first, then keywords), each capped at `maxResults`. **What's the difference between keyword search and advertiser search?** A keyword search matches your text against ad content. Turning on `searchAsAdvertiser` treats your text as an advertiser name and returns that advertiser's ads the same split TikTok shows as "Search this exact phrase" vs "Advertiser name." **Why is the run slow when I enable Download Media or Fetch Ad Detail?** Both add per-ad work. `fetchAdDetail` makes one extra request per ad; `downloadMedia` downloads each ad's video and images (a few seconds per ad) via the [Universal Downloader](https://apify.com/dz_omar/universal-downloader?fpr=smcx63). Enabling both together compounds the time, so a large run (e.g. 1,000 ads) can take substantially longer. Leave them off if you only need metadata and the original (short-lived) media URLs. **Where are downloaded media files stored, and do they expire?** They're saved to your own Apify account's key-value store by the Universal Downloader. On free accounts, unnamed storage expires in about 7 days; on paid accounts it's retained. The original TikTok URLs expire after a few hours regardless that's why Download Media exists. **What happens if the run is aborted or hits a block mid-way?** Results are written in real time, one ad at a time, as they are scraped. Anything already collected is saved. A failing source is skipped and the next one continues one bad input never loses the whole run. **Why did one of my keyword/URL entries get skipped?** Most likely its date range was reversed (`dateFrom` after `dateTo`) or fell entirely outside TikTok's ~1-year retention. The run log states exactly which entry and why. *** ### ⚖️ Legal & Ethical Use This Actor extracts **publicly visible data** from the TikTok Ad Library the same information anyone can see in their browser on library.tiktok.com. **Please use this tool responsibly:** - Only use the data for lawful purposes such as research, competitive analysis, and compliance. - Comply with [TikTok's Terms of Service](https://www.tiktok.com/legal/terms-of-service) and applicable data protection regulations (GDPR, CCPA, etc.). - Do not use extracted data for spam, harassment, or unsolicited outreach. For questions about a specific use case, contact us at . *** ### 🔄 How results are saved Results stream into your dataset **in real time** each ad is pushed the moment it is scraped, in order (URLs first, then keywords). There is no end-of-run batch dump: | Trigger | Behavior | |---|---| | Each ad scraped | Pushed to the dataset immediately | | Source fails or is blocked | That source is skipped; already-pushed ads are retained | | Budget/charge limit reached | Run stops cleanly; everything collected so far is kept | | Run aborted | Already-pushed ads remain in the dataset | *** ### 🚫 Error Handling | Situation | What you see | What to do | |---|---|---| | Reversed dates | `Date From … is after Date To …` | Swap the dates so the start comes first | | Range too old | `range … is entirely older than TikTok's ~1-year retention` | Choose dates within the last year | | Date out of range at runtime | `TikTok rejected the date range as out of its ~1-year retention window` | Narrow the range to the last year | | Initial block | `TikTok blocked the initial request` | Try again later, or enable a proxy | | No valid input | `No scrapeable sources` | Check your URLs, keywords, and dates | *** ### 💬 Support & Contact #### Get Help - 🌐 **Website**: [flowextractapi.com](https://flowextractapi.com) - 📧 **Email**: - 🙋 **Apify Profile**: [FlowExtract API](https://apify.com/dz_omar?fpr=smcx63) - 💬 **GitHub Issues**: [FlowExtractAPI](https://github.com/FlowExtractAPI) #### Social Media - 💼 **LinkedIn**: [flowextract-api](https://www.linkedin.com/in/flowextract-api/) - 🐦 **Twitter**: [@FlowExtractAPI](https://x.com/@FlowExtractAPI) - 📱 **Facebook**: [flowextractapi](https://www.facebook.com/flowextractapi) *** ### 🌟 Related Actors by FlowExtract API #### 🏠 Real Estate Data **[domain.com.au Scraper](https://apify.com/dz_omar/domain-scraper?fpr=smcx63)** Extract Australian property listings from domain.com.au with full enrichment, agent contacts, schools, and market insights. **[Realtor.com Scraper](https://apify.com/dz_omar/realtor-scraper?fpr=smcx63)** Extract US property listings from Realtor.com. Pricing, agent contacts, tax history, AVM estimates, nearby schools, flood and noise data, and full listing history. **[PropertyFinder Scraper](https://apify.com/dz_omar/propertyfinder-scraper?fpr=smcx63)** Extract property listings from PropertyFinder across UAE, Saudi Arabia, Bahrain, Egypt, and Qatar. **[Idealista Scraper API](https://apify.com/dz_omar/idealista-scraper-api?fpr=smcx63)** Advanced Idealista property data extraction with API access. **[Idealista Scraper](https://apify.com/dz_omar/idealista-scraper?fpr=smcx63)** Extract Spanish real estate listings from Idealista. **[Leboncoin.fr Scraper](https://apify.com/dz_omar/leboncoin-scraper?fpr=smcx63)** Extract French classified listings from Leboncoin real estate, vehicles, jobs, and more. **[AI Contact Intelligence Extractor](https://apify.com/dz_omar/ai-contact-intelligence?fpr=smcx63)** Extract emails, phones, contacts & custom data using AI. #### 🍔 Food & Delivery **[DoorDash Scraper](https://apify.com/dz_omar/doordash-scraper?fpr=smcx63)** Scrape store listings, full menus, featured items, and customer reviews from DoorDash. #### 🎬 Video & Media Tools **[YouTube Transcript & Metadata Extractor](https://apify.com/dz_omar/youtube-transcript-metadata?fpr=smcx63)** Extract complete video transcripts with timestamps and comprehensive metadata. **[YouTube Full Channel, Playlists, Shorts, Live](https://apify.com/dz_omar/Youtube-Scraper-Pro?fpr=smcx63)** Extract complete playlist information with all video details from any YouTube playlist. **[Zoom Scraper | Downloader & Transcript](https://apify.com/dz_omar/zoom-scraper?fpr=smcx63)** Extract Zoom meeting recordings, transcripts, and metadata. **[Loom Scraper | Downloader & Transcript](https://apify.com/dz_omar/loom-video-scraper?fpr=smcx63)** Download Loom videos and extract transcripts. #### 🛠️ Developer & Security Tools **[Screenshot](https://apify.com/dz_omar/screenshot?fpr=smcx63)** Fast, reliable webpage screenshots with customizable options. **[Ultimate Screenshot](https://apify.com/dz_omar/ultimate-screenshot?fpr=smcx63)** Advanced screenshot tool with full-page capture, custom viewports, and quality controls. #### 📱 Social Media Tools **[Facebook Ads Scraper Pro](https://apify.com/dz_omar/facebook-ads-scraper-pro?fpr=smcx63)** Extract Facebook ads data for competitor analysis and market research. **[LinkedIn Ad Library Scraper](https://apify.com/dz_omar/linkedin-ads-scraper?fpr=smcx63)** Extract comprehensive advertising data from LinkedIn's Ad Library. *** **Ready to extract TikTok ad data?** [Start using TikTok Ad Library Scraper now!](https://apify.com/dz_omar/tiktok-ad-library-scraper?fpr=smcx63) # Actor input Schema ## `maxResults` (type: `integer`): Maximum number of ads to collect per URL and per keyword filter. Set to 0 to collect everything the API returns (up to the TikTok hard cap of 1,000 per query). Total results = (number of URLs + number of keywords) × Maximum Results. Example: 5 URLs + 6 keywords = 11 inputs. At 16 Maximum Results: 11 × 16 = 176 ads maximum. ## `fetchAdDetail` (type: `boolean`): Whether to fetch detailed information for each ad. If false, only summary information from the search results is collected. If true, the scraper makes an additional request per ad to collect the full advertiser profile, targeting parameters, and impression breakdowns which increases runtime and cost. ## `downloadMedia` (type: `boolean`): Download each ad's video and images to permanent storage and add the download links to the output. ⚠️ This makes the run SIGNIFICANTLY SLOWER every ad triggers a separate download (roughly a few seconds per ad), so 1,000 ads can add a long wait. TikTok's own media links expire after a few hours; this option re-hosts them so they stay accessible. Downloads are handled by the Universal Downloader actor and saved to YOUR account's storage (free accounts: files expire in ~7 days; paid accounts: retained). Leave off if you only need the ad metadata and the original (short-lived) media URLs. ## `startUrls` (type: `array`): One or more full library.tiktok.com/ads URLs. Copy the URL from your browser after applying all filters on the TikTok Ad Library site. ## `keywords` (type: `array`): One or more keyword search configurations. Each entry requires a keyword and optionally a region, date range, and sort order. ## Actor input object example ```json { "maxResults": 10, "fetchAdDetail": false, "downloadMedia": false, "startUrls": [ { "url": "https://library.tiktok.com/ads?region=DE&adv_name=nike&sort_type=last_shown_date,desc" } ], "keywords": [ { "query": "youtube", "region": "DE", "dateFrom": "2026-01-01", "sortOrder": "newest" }, { "query": "pokemon seller", "region": "all", "sortOrder": "popular" } ] } ``` # Actor output Schema ## `results` (type: `string`): All scraped ad records, one object per ad. Includes advertiser, creative type, shown dates, estimated audience, and video/image creatives. Records carry a populated 'details' object only when Fetch Ad Detail was enabled. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startUrls": [ { "url": "https://library.tiktok.com/ads?region=DE&adv_name=nike&sort_type=last_shown_date,desc" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("dz_omar/tiktok-ad-library-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": [{ "url": "https://library.tiktok.com/ads?region=DE&adv_name=nike&sort_type=last_shown_date,desc" }] } # Run the Actor and wait for it to finish run = client.actor("dz_omar/tiktok-ad-library-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "startUrls": [ { "url": "https://library.tiktok.com/ads?region=DE&adv_name=nike&sort_type=last_shown_date,desc" } ] }' | apify call dz_omar/tiktok-ad-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=dz_omar/tiktok-ad-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ad Library - Free To Use", "description": "Scrape ads from the TikTok Ad Library by keyword, advertiser name, or URL. Export advertiser, creative type, first/last shown dates, audience size, video/image creatives, and download media files permanently. Full targeting data (regions, age, gender) on demand. No login required.", "version": "0.0", "x-build-id": "9i6C0urIbFm96EuY1" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dz_omar~tiktok-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dz_omar-tiktok-ad-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/dz_omar~tiktok-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-dz_omar-tiktok-ad-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/dz_omar~tiktok-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-dz_omar-tiktok-ad-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "maxResults": { "title": "Maximum Results Per Input", "minimum": 0, "type": "integer", "description": "Maximum number of ads to collect per URL and per keyword filter. Set to 0 to collect everything the API returns (up to the TikTok hard cap of 1,000 per query).\n\nTotal results = (number of URLs + number of keywords) × Maximum Results.\n\nExample: 5 URLs + 6 keywords = 11 inputs. At 16 Maximum Results: 11 × 16 = 176 ads maximum.", "default": 10 }, "fetchAdDetail": { "title": "🔍 Fetch Ad Detail", "type": "boolean", "description": "Whether to fetch detailed information for each ad. If false, only summary information from the search results is collected. If true, the scraper makes an additional request per ad to collect the full advertiser profile, targeting parameters, and impression breakdowns which increases runtime and cost.", "default": false }, "downloadMedia": { "title": "⬇️ Download Media (video + images)", "type": "boolean", "description": "Download each ad's video and images to permanent storage and add the download links to the output.\n\n⚠️ This makes the run SIGNIFICANTLY SLOWER every ad triggers a separate download (roughly a few seconds per ad), so 1,000 ads can add a long wait. TikTok's own media links expire after a few hours; this option re-hosts them so they stay accessible.\n\nDownloads are handled by the Universal Downloader actor and saved to YOUR account's storage (free accounts: files expire in ~7 days; paid accounts: retained). Leave off if you only need the ad metadata and the original (short-lived) media URLs.", "default": false }, "startUrls": { "title": "Start URLs", "type": "array", "description": "One or more full library.tiktok.com/ads URLs. Copy the URL from your browser after applying all filters on the TikTok Ad Library site.", "items": { "type": "object", "properties": { "url": { "title": "TikTok Ad Library URL", "type": "string", "description": "Direct URL from the TikTok Ad Library. Must start with https://library.tiktok.com/ads", "pattern": "^https://library\\.tiktok\\.com/ads.*" } } }, "default": [ { "url": "https://library.tiktok.com/ads?region=DE&adv_name=nike&sort_type=last_shown_date,desc" } ] }, "keywords": { "title": "Keyword Filters", "type": "array", "description": "One or more keyword search configurations. Each entry requires a keyword and optionally a region, date range, and sort order.", "items": { "type": "object", "properties": { "query": { "title": "Keyword or Advertiser Name", "type": "string", "description": "The keyword or advertiser name to search for.", "editor": "textfield", "minLength": 1, "maxLength": 40 }, "searchAsAdvertiser": { "title": "Search as advertiser", "type": "boolean", "description": "Off (default): treat the text as a keyword and match it against ad content (TikTok's \"Search this exact phrase\"). On: treat the text as an advertiser name and return that advertiser's ads (TikTok's \"Advertiser name\").", "default": false }, "region": { "title": "🌍 Region", "type": "string", "description": "Country to filter by. Selects one region per search the TikTok API processes one region at a time. Use 'All regions' to search across all EU/EEA regions in a single query.", "editor": "select", "enum": [ "all", "AT", "BE", "BG", "CH", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GB", "GR", "HR", "HU", "IE", "IS", "IT", "LI", "LT", "LU", "LV", "MT", "NL", "NO", "PL", "PT", "RO", "SE", "SI", "SK", "TR" ], "enumTitles": [ "All regions (EU/EEA)", "Austria", "Belgium", "Bulgaria", "Switzerland", "Cyprus", "Czech Republic", "Germany", "Denmark", "Estonia", "Spain", "Finland", "France", "United Kingdom", "Greece", "Croatia", "Hungary", "Ireland", "Iceland", "Italy", "Liechtenstein", "Lithuania", "Luxembourg", "Latvia", "Malta", "Netherlands", "Norway", "Poland", "Portugal", "Romania", "Sweden", "Slovenia", "Slovakia", "Turkey" ], "default": "all" }, "dateFrom": { "title": "Date From", "type": "string", "description": "Start date for the search range. Defaults to 2016-01-01 if omitted.", "editor": "datepicker", "example": "2026-01-01" }, "dateTo": { "title": "Date To", "type": "string", "description": "End date for the search range. Defaults to today if omitted.", "editor": "datepicker", "example": "2026-06-03" }, "sortOrder": { "title": "Sort Order", "type": "string", "description": "How to sort results for this keyword search.", "editor": "select", "enum": [ "newest", "oldest", "created", "created-asc", "popular", "unpopular" ], "enumTitles": [ "Newest first (last shown date ↓)", "Oldest first (last shown date ↑)", "Recently created first", "Oldest created first", "Most popular first (unique viewers ↓)", "Least popular first (unique viewers ↑)" ], "default": "newest" } }, "required": [ "query" ], "additionalProperties": false } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```