# Tiktok One Scraper (`doliz/tiktok-one-scraper`) Actor All In One for TikTok One Top Ads research. Extract structured data from official Top Ads Insight and Top Ads Library workflows, including overview metrics, creative approaches, selling point analysis, material lists, library search results, and material details. - **URL**: https://apify.com/doliz/tiktok-one-scraper.md - **Developed by:** [doliz](https://apify.com/doliz) (community) - **Categories:** Social media, E-commerce, News - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## 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 One Scraper [中文 README](https://github.com/lofe-w/tiktok-one-scraper-public/blob/main/README.zh-CN.md) All In One! A focused scraper for the official TikTok One Top Ads surfaces available today. Reliably extract structured Top Ads Insight metrics, creative approach formulas, selling point analysis, Top Ads material lists, Top Ads Library search results, and material details for marketing intelligence, competitive research, and creative analysis. [Start Now (On Apify)](https://apify.com/doliz/tiktok-one-scraper) ### ✨ Key Features * **⚡️ Fast & Efficient**: Bypasses slow UI interactions by calling TikTok One backend APIs directly, saving time and platform costs. * **🎯 All-in-one Top Ads Scraping**: One Actor covering the currently implemented official TikTok One Top Ads workflows, including: * [Top Ads Insight](https://ads.tiktok.com/creative/inspiration/top-ads/insight) * [Top Ads Library](https://ads.tiktok.com/creative/inspiration/top-ads/library) * Creative Approach formulas * Selling Point Analysis categories * Top 20 selling points by category * Creative Approach material lists * Selling Point Analysis material lists * Material detail lookup * **🔎 Powerful Filtering**: Use TikTok One's official industry, country, time range, objective, likes percentile, and sorting fields where the current product exposes them. * **📦 Structured JSON Output**: Get clean, machine-readable data ready for dashboards, enrichment pipelines, competitive monitoring, and ad research workflows. * **🧭 Officially Aligned Scope**: This Actor follows the current TikTok One Top Ads product scope and only exposes implemented, runnable targets. ### 💡 Best practices This Actor operates by directly accessing TikTok One backend APIs. TikTok may apply undisclosed authentication checks and rate limits. To keep runs stable and avoid throttling, we strongly recommend the following best practices: #### 💡 Use valid TikTok One cookies Use cookies from an account that can open the TikTok One Top Ads pages in a browser. If cookies are missing, expired, invalid, or blocked by TikTok, upstream requests may fail or return authentication errors. #### 💡 Utilize multiple accounts (cookies) For frequent or high-volume scraping, provide a pool of account cookies and rotate through them for different requests. This distributes request load and reduces the risk of any single account being rate-limited. #### 💡 Limit the number of concurrent requests For scheduled or bulk workflows, too many concurrent upstream requests may be throttled. You can implement [Rate Limiting](https://en.wikipedia.org/wiki/Rate_limiting) on the client side. A common approach is the [Token Bucket Algorithm](https://en.wikipedia.org/wiki/Token_bucket): tokens are issued according to your rate limit rule, and each request must obtain a token before it starts. A more robust implementation is to use [Message Queuing](https://en.wikipedia.org/wiki/Message_queue). Push scraping tasks to a queue, let dedicated consumers process them, limit the number of concurrent consumers, and retry failed tasks later. ### ⚙️ Input Configuration #### ⚙️ Main * **Target** `target`: (Required) Select the TikTok One data source. Your choice determines which settings below are used. One of `top_ads_insight`, `top_ads_insight_creative_approach`, `top_ads_insight_selling_point_analysis`, `top_ads_insight_top20_selling_points`, `top_ads_insight_formula_material_list`, `top_ads_insight_selling_point_material_list`, `top_ads_insight_material_detail`, `top_ads_library`, `top_ads_library_material_detail`. * **Cookies** `cookies`: (Required) Your authentication cookies after logging into TikTok One on `ads.tiktok.com`. Way to obtain: ![](https://github.com/lofe-w/tiktok-one-scraper-public/raw/main/imgs/get_cookie.png) --- #### ⚙️ Top Ads Insight Settings (`top_ads_insight`) These settings are only used when `Target` is set to `top_ads_insight`. * **Industry label** `insight_industry_label`: (Required) Official industry label. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) * **Country code** `insight_country_code`: (Required) Official country or region filter. Leave empty for `All`. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) * **Time range** `insight_time_range`: (Required) Publication time range. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) * **Sort by** `insight_order_field`: (Required) Ranking metric used by related insight requests. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) The `top_ads_insight` target mirrors the initial Top Ads Insight page load. It returns overview metrics, Creative Approach formulas, Selling Point Analysis categories, and Top 20 selling points for the first categories returned by TikTok One. --- #### ⚙️ Top Ads Insight - Creative Approach Settings (`top_ads_insight_creative_approach`) These settings are only used when `Target` is set to `top_ads_insight_creative_approach`. * **Industry label** `insight_creative_industry_label`: (Required) Official industry label. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) * **Country code** `insight_creative_country_code`: (Required) Official country or region filter. Leave empty for `All`. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) * **Time range** `insight_creative_time_range`: (Required) Publication time range. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) * **Sort by** `insight_creative_order_field`: (Required) Ranking metric. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) Use `formulaList[].id` from this target as `insight_formula_material_formula_id` when fetching Creative Approach materials. --- #### ⚙️ Top Ads Insight - Selling Point Analysis Settings (`top_ads_insight_selling_point_analysis`) These settings are only used when `Target` is set to `top_ads_insight_selling_point_analysis`. * **Industry label** `insight_selling_industry_label`: (Required) Official industry label. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) * **Country code** `insight_selling_country_code`: (Required) Official country or region filter. Leave empty for `All`. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) * **Time range** `insight_selling_time_range`: (Required) Publication time range. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) * **Sort by** `insight_selling_order_field`: (Required) Ranking metric. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) Use `SellingPoints[].categoryName` from this target as `insight_top20_category` when fetching Top 20 selling points. --- #### ⚙️ Top Ads Insight - Top 20 Selling Points Settings (`top_ads_insight_top20_selling_points`) These settings are only used when `Target` is set to `top_ads_insight_top20_selling_points`. * **Industry label** `insight_top20_industry_label`: (Required) Official industry label. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) * **Country code** `insight_top20_country_code`: (Required) Official country or region filter. Leave empty for `All`. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) * **Time range** `insight_top20_time_range`: (Required) Publication time range. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) * **Sort by** `insight_top20_order_field`: (Required) Ranking metric. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) * **Category** `insight_top20_category`: (Required) Use `SellingPoints[].categoryName` from `top_ads_insight_selling_point_analysis`. --- #### ⚙️ Top Ads Insight - Creative Approach Materials Settings (`top_ads_insight_formula_material_list`) These settings are only used when `Target` is set to `top_ads_insight_formula_material_list`. * **Industry label** `insight_formula_material_industry_label`: (Required) Official industry label. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) * **Country code** `insight_formula_material_country_code`: (Required) Official country or region filter. Leave empty for `All`. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) * **Time range** `insight_formula_material_time_range`: (Required) Publication time range. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) * **Sort by** `insight_formula_material_order_field`: (Required) Ranking metric. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) * **Formula ID** `insight_formula_material_formula_id`: (Required) Use `formulaList[].id` from `top_ads_insight_creative_approach`. * **Page** `insight_formula_material_page`: (Required) Page number. * **Limit** `insight_formula_material_limit`: (Required) Number of records per page. Valid range: `1` to `10000`. Use `itemList[].materialID` from this target as `insight_detail_material_id` when fetching a Top Ads Insight material detail. --- #### ⚙️ Top Ads Insight - Selling Point Analysis Materials Settings (`top_ads_insight_selling_point_material_list`) These settings are only used when `Target` is set to `top_ads_insight_selling_point_material_list`. * **Industry label** `insight_selling_material_industry_label`: (Required) Official industry label. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) * **Country code** `insight_selling_material_country_code`: (Required) Official country or region filter. Leave empty for `All`. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) * **Time range** `insight_selling_material_time_range`: (Required) Publication time range. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) * **Sort by** `insight_selling_material_order_field`: (Required) Ranking metric. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) * **Selling point** `insight_selling_material_selling_point`: (Required) Use `SellingPoints[].sellingPointName` from `top_ads_insight_top20_selling_points`. * **Page** `insight_selling_material_page`: (Required) Page number. * **Limit** `insight_selling_material_limit`: (Required) Number of records per page. Valid range: `1` to `10000`. Use `itemList[].materialID` from this target as `insight_detail_material_id` when fetching a Top Ads Insight material detail. --- #### ⚙️ Top Ads Insight - Material Detail Settings (`top_ads_insight_material_detail`) These settings are only used when `Target` is set to `top_ads_insight_material_detail`. * **Insight material ID** `insight_detail_material_id`: (Required) Use `itemList[].materialID` from `top_ads_insight_formula_material_list` or `top_ads_insight_selling_point_material_list`. --- #### ⚙️ Top Ads Library Settings (`top_ads_library`) These settings are only used when `Target` is set to `top_ads_library`. * **Industry label** `library_industry_label`: (Optional) Industry label ID. Leave empty for all industries. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_industry.json) * **Country code** `library_country_code`: (Optional) Country or region code. Leave empty for all countries and regions. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_country.json) * **Time range** `library_time_range`: (Required) Publication time range. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_time_range.json) * **Search word** `library_search_word`: (Optional) Search by brand, product, or creative keyword. * **Objective** `library_objective`: (Optional) Campaign objective. Leave empty for all objectives. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_objective.json) * **Likes percentile** `library_like_cnt_filter`: (Optional) Like count percentile filter. Leave empty for all percentiles. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_like_cnt_filter.json) * **Sort by** `library_order_field`: (Required) Metric used to sort results. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_order_field.json) * **Page** `library_page`: (Required) Page number. * **Limit** `library_limit`: (Required) Number of records per page. Valid range: `1` to `50`. Use `itemList[].materialID` from this target as `library_material_id` when fetching a Top Ads Library material detail. --- #### ⚙️ Top Ads Library - Material Detail Settings (`top_ads_library_material_detail`) These settings are only used when `Target` is set to `top_ads_library_material_detail`. * **Material ID** `library_material_id`: (Required) Use `itemList[].materialID` from `top_ads_library`. --- ### 📊 Output Structure The Actor returns a dataset of items. The structure of each item depends on the `target` you selected. **NOTE**: The following are real sample structures from TikTok One API responses. The actual output may contain more fields. Please refer to the output of a sample run for the exact schema. --- #### 📊 Top Ads Insight (`top_ads_insight`) ```json { "dataInsight": { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "clickRate": 0.01861966174097709, "engagementRate": 0.004667982359031695, "videoView": "2923411862", "videoView6sRate": 0.13300873819879164 }, "creativeApproach": { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "formulaList": [ { "clickRate": 0.01532804205489521, "content": [ "Function/Attribute", "Physical product/Commodity", "Applicable Scenarios", "Target Audience" ], "engagementRate": 0.003626492592307972, "id": "[Function/Attribute, Physical product/Commodity, Applicable Scenarios, Target Audience]", "postNumPct": 0.10424275523091102, "videoView": "725058423", "videoView6sRate": 0.1357802376705856 }, ... /* omit */ ] }, "sellingPointAnalysis": { "category": { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "SellingPoints": [ { "categoryName": "Target Audience", "clickRate": 0.015131855660077015, "clickRateWow": -0.021820344372670414, "engagementRate": 0.006421364107410872, "engagementRateWow": 0.037459146764485536, "postNumPct": 0.8560120182585081, "sellingPointName": "", "videoView": "7085131950", "videoView6sRate": 0.12949835648438418, "videoView6sRateWow": -0.013653260524311877, "videoViewWow": 0.47982782334909313 }, ... /* omit */ ] }, "top20SellingPoints": [ { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "SellingPoints": [ { "categoryName": "Target Audience", "clickRate": 0.013211661428313998, "clickRateWow": -0.04245137306068203, "engagementRate": 0.0031889771656263264, "engagementRateWow": -0.06709534547129498, "postNumPct": 0.10068180504997976, "sellingPointName": "Homeowners and Maintenance Enthusiasts", "videoView": "836561023", "videoView6sRate": 0.14181924418919528, "videoView6sRateWow": -0.03342331175429736, "videoViewWow": 0.5779036729199662 }, ... /* omit */ ] }, ... /* omit */ ] } } ```` *** #### 📊 Top Ads Insight - Creative Approach (`top_ads_insight_creative_approach`) ```json { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "formulaList": [ { "clickRate": 0.01532804205489521, "content": [ "Function/Attribute", "Physical product/Commodity", "Applicable Scenarios", "Target Audience" ], "engagementRate": 0.003626492592307972, "id": "[Function/Attribute, Physical product/Commodity, Applicable Scenarios, Target Audience]", "postNumPct": 0.10424275523091102, "videoView": "725058423", "videoView6sRate": 0.1357802376705856 }, ... /* omit */ ] } ``` *** #### 📊 Top Ads Insight - Selling Point Analysis (`top_ads_insight_selling_point_analysis`) ```json { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "SellingPoints": [ { "categoryName": "Target Audience", "clickRate": 0.015131855660077015, "clickRateWow": -0.021820344372670414, "engagementRate": 0.006421364107410872, "engagementRateWow": 0.037459146764485536, "postNumPct": 0.8560120182585081, "sellingPointName": "", "videoView": "7085131950", "videoView6sRate": 0.12949835648438418, "videoView6sRateWow": -0.013653260524311877, "videoViewWow": 0.47982782334909313 }, ... /* omit */ ] } ``` *** #### 📊 Top Ads Insight - Top 20 Selling Points (`top_ads_insight_top20_selling_points`) ```json { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "SellingPoints": [ { "categoryName": "Target Audience", "clickRate": 0.013211661428313998, "clickRateWow": -0.04245137306068203, "engagementRate": 0.0031889771656263264, "engagementRateWow": -0.06709534547129498, "postNumPct": 0.10068180504997976, "sellingPointName": "Homeowners and Maintenance Enthusiasts", "videoView": "836561023", "videoView6sRate": 0.14181924418919528, "videoView6sRateWow": -0.03342331175429736, "videoViewWow": 0.5779036729199662 }, ... /* omit */ ] } ``` *** #### 📊 Top Ads Insight - Creative Approach Materials (`top_ads_insight_formula_material_list`) ```json { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "itemList": [ { "brandName": "", "clickRate": 0, "commentCnt": "0", "countryCodeList": [ "SA" ], "ctrRank": 0.66, "engagementRate": 0.00036005527335007106, "industry": "18000000000", "landingPage": "", "likeCnt": "0", "materialID": "7637823224530026516", "shareCnt": "0", "title": "احمي اثاثك مع بخاخ نانو فور لايف", "videoInfo": { "cover": "https://p19-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oYDfXgPVQCNf9IE6JfbAGX7DJCJwwA7ULDAgFT~tplv-photomode-zoomcover-tcm:720:720.avif?dr=16670&refresh_token=c241a2c4&x-expires=1781740800&x-signature=jSOpVOxf%2FV4pFCjlNMt%2FS%2BmJ5x4%3D&t=e8257cf9&ps=933b5bde&shp=c8b38fb9&shcp=c8b38fb9&idc=my2", "duration": 21.316, "height": "1280", "vid": "v10033g50000d7vg15fog65tgqjqdts0", "video_url": { "720p": "https://v16m-default.tiktokcdn.com/a910ff2b45523eb66f31e225e9c6a627/6a2ab814/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQ9eM839ZQTAief79APAWK67AHtfAgahfMwlkS/?a=0&bti=NTU4QDM1NGA%3D&&bt=1801&ft=cApXJCz7ThWHzMr9LGZmo0P&mime_type=video_mp4&rc=aGY7Z2k4ODlmODNoPDU8NUBpM3d0dHc5cjhqOjMzODYzNEA0NV4tMTJeNS4xMzYxMWNiYSNwYWdkMmRjLnNhLS1kMC1zcw%3D%3D&vvpl=1&l=202606111528313D38198328B44E682ADF&btag=e000b8000" }, "width": "720" }, "videoView": "411048", "videoView6sRank": 0.73, "videoView6sRate": 0 }, ... /* omit */ ], "pagination": { "hasMore": false, "page": "1", "size": "2", "total": "2" } } ``` *** #### 📊 Top Ads Insight - Selling Point Analysis Materials (`top_ads_insight_selling_point_material_list`) ```json { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "itemList": [ { "brandName": "", "clickRate": 0, "commentCnt": "0", "countryCodeList": [ "SA" ], "ctrRank": 0.66, "engagementRate": 0.00036005527335007106, "industry": "18000000000", "landingPage": "", "likeCnt": "0", "materialID": "7637823224530026516", "shareCnt": "0", "title": "احمي اثاثك مع بخاخ نانو فور لايف", "videoInfo": { "cover": "https://p19-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oYDfXgPVQCNf9IE6JfbAGX7DJCJwwA7ULDAgFT~tplv-photomode-zoomcover-tcm:720:720.avif?dr=16670&refresh_token=c241a2c4&x-expires=1781740800&x-signature=jSOpVOxf%2FV4pFCjlNMt%2FS%2BmJ5x4%3D&t=e8257cf9&ps=933b5bde&shp=c8b38fb9&shcp=c8b38fb9&idc=my2", "duration": 21.316, "height": "1280", "vid": "v10033g50000d7vg15fog65tgqjqdts0", "video_url": { "720p": "https://v16m-default.tiktokcdn.com/357714a02f5b0c88d30efdab610f5721/6a2ac293/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQ9eM839ZQTAief79APAWK67AHtfAgahfMwlkS/?a=0&bti=NTU4QDM1NGA%3D&&bt=1801&ft=cApXJCz7ThWH9Rr9LGZmo0P&mime_type=video_mp4&rc=aGY7Z2k4ODlmODNoPDU8NUBpM3d0dHc5cjhqOjMzODYzNEA0NV4tMTJeNS4xMzYxMWNiYSNwYWdkMmRjLnNhLS1kMC1zcw%3D%3D&vvpl=1&l=202606111613186D2D026BFB0E135F48DD&btag=e000b8000" }, "width": "720" }, "videoView": "411048", "videoView6sRank": 0.73, "videoView6sRate": 0 }, ... /* omit */ ], "pagination": { "hasMore": true, "page": "1", "size": "2", "total": "3" } } ``` *** #### 📊 Top Ads Insight - Material Detail (`top_ads_insight_material_detail`) ```json { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "itemInfo": { "brandName": "", "clickRate": 0, "commentCnt": "0", "countryCodeList": [ "SA" ], "ctrRank": 0.66, "engagementRate": 0.00036005527335007106, "industry": "18000000000", "keyFrameInfo": [ { "click_cnt": 0.2391304347826087, "convert_cnt": 0, "play_retain_cnt": 1, "retain_ctr": 0.03143979992854591, "retain_cvr": 0, "second": "0" }, ... /* omit */ ], "landingPage": "https://nano4life-sa.com/ar?utm_source=tiktok&utm_medium=paid&utm_id=__CAMPAIGN_ID__&utm_campaign=__CAMPAIGN_NAME__", "likeCnt": "147", "materialID": "7637823224530026516", "objective": [ 5 ], "shareCnt": "1", "title": "احمي اثاثك مع بخاخ نانو فور لايف", "videoInfo": { "cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oYDfXgPVQCNf9IE6JfbAGX7DJCJwwA7ULDAgFT~tplv-noop.image?dr=18692&refresh_token=1d20876a&x-expires=1781187224&x-signature=qHW3teAeUrAmlZhcBCYIx54A9zY%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my2&VideoID=v10033g50000d7vg15fog65tgqjqdts0", "duration": 21.316, "height": "1280", "vid": "v10033g50000d7vg15fog65tgqjqdts0", "video_url": { "720p": "https://v16m-default.tiktokcdn.com/b3c2444addc896d7993d3618eda3b1a5/6a2ac298/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQ9eM839ZQTAief79APAWK67AHtfAgahfMwlkS/?a=0&bti=NTU4QDM1NGA%3D&&bt=1801&ft=cApXJCz7ThWH4Rr9LGZmo0P&mime_type=video_mp4&rc=aGY7Z2k4ODlmODNoPDU8NUBpM3d0dHc5cjhqOjMzODYzNEA0NV4tMTJeNS4xMzYxMWNiYSNwYWdkMmRjLnNhLS1kMC1zcw%3D%3D&vvpl=1&l=20260611161323C6AD417FBB95886B2486&btag=e000b8000" }, "width": "720" }, "videoView": "411048", "videoView6sRank": 0.73, "videoView6sRate": 0 } } ``` *** #### 📊 Top Ads Library (`top_ads_library`) ```json { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "itemList": [ { "adv_id": [ "7372413843525517313" ], "brandName": "", "clickRate": 0, "commentCnt": "0", "countryCodeList": [ "PH" ], "ctrRank": 0.04, "engagementRate": 0.0010963407354446612, "industry": "23125000000", "landingPage": "", "likeCnt": "0", "materialID": "7644457820796878856", "objective": [ 5 ], "shareCnt": "0", "title": "Pabangisin ang bonding ng tropa with Foodvencha. #TikmanAngAdvencha P0173P052526M", "videoInfo": { "cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/o01V469EWVvE5h6iWsuNnpYmBGIaAibaLB9AI~tplv-photomode-zoomcover-tcm:720:720.avif?dr=16670&refresh_token=a327d82d&x-expires=1781748000&x-signature=g%2BKhapyPyF7CntIv%2FXghBzDZMwY%3D&t=e8257cf9&ps=933b5bde&shp=c8b38fb9&shcp=c8b38fb9&idc=my", "duration": 15.022, "height": "1280", "vid": "v14044g50000d8aplpnog65tjr3c996g", "video_url": { "720p": "https://v16m-default.tiktokcdn.com/a9b53b615ecfa7f5c90c4fdf794e5f4a/6a2ab825/video/tos/alisg/tos-alisg-pve-0037c001/okSgbQEhYEAuasAWBkWVIEpNFLvkp5ihn9Bia/?a=0&bti=NTU4QDM1NGA%3D&&bt=2884&ft=cApXJCz7ThWHeMr9LGZmo0P&mime_type=video_mp4&rc=aTszNjg5OWVpPGZoZGRpZ0BpajxmdXc5cnNzOzMzODczNEAzMi9iMGFhNTMxNi5hMWFjYSMzNjBnMmRraV5hLS1kMTFzcw%3D%3D&vvpl=1&l=202606111528544E4EA3BB5EA48867FD7A&btag=e000b8000" }, "width": "720" }, "videoView": "82856540", "videoView6sRank": 0.08, "videoView6sRate": 0.1343032426572047 }, ... /* omit */ ], "pagination": { "hasMore": true, "page": "1", "size": "2", "total": "500" } } ``` *** #### 📊 Top Ads Library - Material Detail (`top_ads_library_material_detail`) ```json { "BaseResp": { "StatusCode": 0, "StatusMessage": "" }, "itemInfo": { "brandName": "", "clickRate": 0, "commentCnt": "675", "countryCodeList": [ "PH" ], "ctrRank": 0.04, "engagementRate": 0.0010963407354446612, "industry": "23000000000", "keyFrameInfo": [ { "click_cnt": 0.7028168762184107, "convert_cnt": 0, "play_retain_cnt": 1, "retain_ctr": 0.4027917084587095, "retain_cvr": 0, "second": "0" }, ... /* omit */ ], "landingPage": "https://www.klook.com/en-PH/tetris/promo/dewfoodvenchatour/", "likeCnt": "89051", "materialID": "7644457820796878856", "objective": [ 5 ], "shareCnt": "1113", "title": "Pabangisin ang bonding ng tropa with Foodvencha. #TikmanAngAdvencha P0173P052526M", "videoInfo": { "cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/o01V469EWVvE5h6iWsuNnpYmBGIaAibaLB9AI~tplv-noop.image?dr=18692&refresh_token=bff93274&x-expires=1781184550&x-signature=Qsoq1AIxg7tDb01r%2F9pqZy%2BRizI%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my2&VideoID=v14044g50000d8aplpnog65tjr3c996g", "duration": 15.022, "height": "1280", "vid": "v14044g50000d8aplpnog65tjr3c996g", "video_url": { "720p": "https://v16m-default.tiktokcdn.com/d6221c39c77ff604a181e6e9df87799a/6a2ab826/video/tos/alisg/tos-alisg-pve-0037c001/okSgbQEhYEAuasAWBkWVIEpNFLvkp5ihn9Bia/?a=0&bti=NTU4QDM1NGA%3D&&bt=2884&ft=cApXJCz7ThWHsMr9LGZmo0P&mime_type=video_mp4&rc=aTszNjg5OWVpPGZoZGRpZ0BpajxmdXc5cnNzOzMzODczNEAzMi9iMGFhNTMxNi5hMWFjYSMzNjBnMmRraV5hLS1kMTFzcw%3D%3D&vvpl=1&l=202606111528552512DCABE9F7496A60E3&btag=e000b8000" }, "width": "720" }, "videoView": "82856540", "videoView6sRank": 0.08, "videoView6sRate": 0 } } ``` *** ### 💰 Cost of Use & Pricing Pricing model: [Pay per event](https://docs.apify.com/platform/actors/publishing/monetize/pay-per-event) The trigger logic of the event is the number of items that return the result. | Target | Cost | |---|---| | [Top Ads Insight](https://ads.tiktok.com/creative/inspiration/top-ads/insight) | 0.002$ / fetched item | | [Top Ads Insight - Creative Approach](https://ads.tiktok.com/creative/inspiration/top-ads/insight) | 0.002$ / item | | [Top Ads Insight - Selling Point Analysis](https://ads.tiktok.com/creative/inspiration/top-ads/insight) | 0.002$ / item | | [Top Ads Insight - Top 20 Selling Points](https://ads.tiktok.com/creative/inspiration/top-ads/insight) | 0.002$ / item | | [Top Ads Insight - Creative Approach Materials](https://ads.tiktok.com/creative/inspiration/top-ads/insight) | 0.002$ / item | | [Top Ads Insight - Selling Point Analysis Materials](https://ads.tiktok.com/creative/inspiration/top-ads/insight) | 0.002$ / item | | [Top Ads Insight - Material Detail](https://ads.tiktok.com/creative/inspiration/top-ads/insight) | 0.002$ / time | | [Top Ads Library](https://ads.tiktok.com/creative/inspiration/top-ads/library) | 0.002$ / item | | [Top Ads Library - Material Detail](https://ads.tiktok.com/creative/inspiration/top-ads/library) | 0.002$ / time | Unknown or unsupported targets are rejected before any upstream request or charge. ### 📞 Support If you encounter any issues or have feature requests, please use the **Issues** tab on the Actor's page in the Apify Console. Please provide a detailed description of the problem and the Run ID. ### ⚠️ Limitations and Disclaimers - This Actor is not an official TikTok product and is not affiliated with or endorsed by TikTok, Inc. - The structure of the TikTok One website and its internal APIs may change at any time. - TikTok One requests require valid logged-in cookies from `ads.tiktok.com`; expired, invalid, rate-limited, or unauthorized cookies can cause upstream failures. - Some Top Ads Insight endpoints require browser-side request signatures. The Actor handles these internally, but successful access still depends on TikTok One accepting the account session. - Please use this Actor responsibly and in accordance with the Apify Terms of Service. # Actor input Schema ## `target` (type: `string`): Select a TikTok One data source. ## `cookies` (type: `string`): Your TikTok One authentication cookies. Way to obtain: ![](https://github.com/lofe-w/tiktok-one-scraper-public/raw/main/imgs/get_cookie.png) ## `insight_industry_label` (type: `string`): Official industry label for Top Ads Insight. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) ## `insight_country_code` (type: `string`): Official country or region filter for Top Ads Insight. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) ## `insight_time_range` (type: `string`): Publication time range for Top Ads Insight. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) ## `insight_order_field` (type: `string`): Ranking matrix used by Top Ads Insight. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) ## `insight_creative_industry_label` (type: `string`): Official industry label for Top Ads Insight - Creative Approach. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) ## `insight_creative_country_code` (type: `string`): Official country or region filter for Top Ads Insight - Creative Approach. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) ## `insight_creative_time_range` (type: `string`): Publication time range for Top Ads Insight - Creative Approach. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) ## `insight_creative_order_field` (type: `string`): Ranking matrix used by Top Ads Insight - Creative Approach. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) ## `insight_selling_industry_label` (type: `string`): Official industry label for Top Ads Insight - Selling Point Analysis. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) ## `insight_selling_country_code` (type: `string`): Official country or region filter for Top Ads Insight - Selling Point Analysis. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) ## `insight_selling_time_range` (type: `string`): Publication time range for Top Ads Insight - Selling Point Analysis. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) ## `insight_selling_order_field` (type: `string`): Ranking matrix used by Top Ads Insight - Selling Point Analysis. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) ## `insight_top20_industry_label` (type: `string`): Official industry label for Top Ads Insight - Top 20 Selling Points. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) ## `insight_top20_country_code` (type: `string`): Official country or region filter for Top Ads Insight - Top 20 Selling Points. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) ## `insight_top20_time_range` (type: `string`): Publication time range for Top Ads Insight - Top 20 Selling Points. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) ## `insight_top20_order_field` (type: `string`): Ranking matrix used by Top Ads Insight - Top 20 Selling Points. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) ## `insight_top20_category` (type: `string`): Use `SellingPoints[].categoryName` from `Top Ads Insight - Selling Point Analysis`; required by `Top Ads Insight - Top 20 Selling Points`. ## `insight_formula_material_industry_label` (type: `string`): Official industry label for Top Ads Insight - Creative Approach Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) ## `insight_formula_material_country_code` (type: `string`): Official country or region filter for Top Ads Insight - Creative Approach Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) ## `insight_formula_material_time_range` (type: `string`): Publication time range for Top Ads Insight - Creative Approach Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) ## `insight_formula_material_order_field` (type: `string`): Ranking matrix used by Top Ads Insight - Creative Approach Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) ## `insight_formula_material_formula_id` (type: `string`): Use `formulaList[].id` from `Top Ads Insight - Creative Approach`. ## `insight_formula_material_page` (type: `integer`): Page number for Top Ads Insight - Creative Approach Materials. ## `insight_formula_material_limit` (type: `integer`): Number of Top Ads Insight - Creative Approach Materials records per page. ## `insight_selling_material_industry_label` (type: `string`): Official industry label for Top Ads Insight - Selling Point Analysis Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json) ## `insight_selling_material_country_code` (type: `string`): Official country or region filter for Top Ads Insight - Selling Point Analysis Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json) ## `insight_selling_material_time_range` (type: `string`): Publication time range for Top Ads Insight - Selling Point Analysis Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json) ## `insight_selling_material_order_field` (type: `string`): Ranking matrix used by Top Ads Insight - Selling Point Analysis Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json) ## `insight_selling_material_selling_point` (type: `string`): Use `SellingPoints[].sellingPointName` from `Top Ads Insight - Top 20 Selling Points`. ## `insight_selling_material_page` (type: `integer`): Page number for Top Ads Insight - Selling Point Analysis Materials. ## `insight_selling_material_limit` (type: `integer`): Number of Top Ads Insight - Selling Point Analysis Materials records per page. ## `insight_detail_material_id` (type: `string`): Use `itemList[].materialID` from `Top Ads Insight - Creative Approach Materials` or `Top Ads Insight - Selling Point Analysis Materials`. ## `library_industry_label` (type: `string`): Official industry label for Top Ads Library. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_industry.json) ## `library_country_code` (type: `string`): Official country or region filter for Top Ads Library. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_country.json) ## `library_time_range` (type: `string`): Publication time range for Top Ads Library. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_time_range.json) ## `library_search_word` (type: `string`): Search by brand, product, or creative keyword. ## `library_objective` (type: `string`): Campaign objective. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_objective.json) ## `library_like_cnt_filter` (type: `string`): Like count percentile filter. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_like_cnt_filter.json) ## `library_order_field` (type: `string`): Metric used to sort Top Ads Library results. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_order_field.json) ## `library_page` (type: `integer`): Page number for Top Ads Library results. ## `library_limit` (type: `integer`): Number of Top Ads Library records per page. ## `library_material_id` (type: `string`): Use `itemList[].materialID` from `Top Ads Library`. ## Actor input object example ```json { "target": "top_ads_insight", "cookies": "Your cookies", "insight_industry_label": "18000000000", "insight_country_code": "", "insight_time_range": "30", "insight_order_field": "1", "insight_creative_industry_label": "18000000000", "insight_creative_country_code": "", "insight_creative_time_range": "30", "insight_creative_order_field": "1", "insight_selling_industry_label": "18000000000", "insight_selling_country_code": "", "insight_selling_time_range": "30", "insight_selling_order_field": "1", "insight_top20_industry_label": "18000000000", "insight_top20_country_code": "", "insight_top20_time_range": "30", "insight_top20_order_field": "1", "insight_formula_material_industry_label": "18000000000", "insight_formula_material_country_code": "", "insight_formula_material_time_range": "30", "insight_formula_material_order_field": "1", "insight_formula_material_page": 1, "insight_formula_material_limit": 20, "insight_selling_material_industry_label": "18000000000", "insight_selling_material_country_code": "", "insight_selling_material_time_range": "30", "insight_selling_material_order_field": "1", "insight_selling_material_page": 1, "insight_selling_material_limit": 20, "library_industry_label": "", "library_country_code": "", "library_time_range": "30", "library_objective": "", "library_like_cnt_filter": "", "library_order_field": "1", "library_page": 1, "library_limit": 20 } ``` # 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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("doliz/tiktok-one-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 = {} # Run the Actor and wait for it to finish run = client.actor("doliz/tiktok-one-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 '{}' | apify call doliz/tiktok-one-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=doliz/tiktok-one-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Tiktok One Scraper", "description": "All In One for TikTok One Top Ads research. Extract structured data from official Top Ads Insight and Top Ads Library workflows, including overview metrics, creative approaches, selling point analysis, material lists, library search results, and material details.", "version": "0.1", "x-build-id": "XQ4gtHmCrBu3m9e55" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/doliz~tiktok-one-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-doliz-tiktok-one-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/doliz~tiktok-one-scraper/runs": { "post": { "operationId": "runs-sync-doliz-tiktok-one-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/doliz~tiktok-one-scraper/run-sync": { "post": { "operationId": "run-sync-doliz-tiktok-one-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", "required": [ "target", "cookies" ], "properties": { "target": { "title": "Target", "enum": [ "top_ads_insight", "top_ads_insight_creative_approach", "top_ads_insight_selling_point_analysis", "top_ads_insight_top20_selling_points", "top_ads_insight_formula_material_list", "top_ads_insight_selling_point_material_list", "top_ads_insight_material_detail", "top_ads_library", "top_ads_library_material_detail" ], "type": "string", "description": "Select a TikTok One data source.", "default": "top_ads_insight" }, "cookies": { "title": "Cookies", "type": "string", "description": "Your TikTok One authentication cookies. Way to obtain: ![](https://github.com/lofe-w/tiktok-one-scraper-public/raw/main/imgs/get_cookie.png)", "default": "Your cookies" }, "insight_industry_label": { "title": "Industry label", "enum": [ "18000000000", "14000000000", "22000000000", "29000000000", "16000000000", "28000000000", "20000000000" ], "type": "string", "description": "Official industry label for Top Ads Insight. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json)", "default": "18000000000" }, "insight_country_code": { "title": "Country code", "enum": [ "", "US", "JP", "ID", "TH", "MY", "VN", "GB", "FR", "PH", "SA", "ZA", "KR", "ES", "MX" ], "type": "string", "description": "Official country or region filter for Top Ads Insight. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json)", "default": "" }, "insight_time_range": { "title": "Time range", "enum": [ "7", "30" ], "type": "string", "description": "Publication time range for Top Ads Insight. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json)", "default": "30" }, "insight_order_field": { "title": "Sort by", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Ranking matrix used by Top Ads Insight. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json)", "default": "1" }, "insight_creative_industry_label": { "title": "Industry label", "enum": [ "18000000000", "14000000000", "22000000000", "29000000000", "16000000000", "28000000000", "20000000000" ], "type": "string", "description": "Official industry label for Top Ads Insight - Creative Approach. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json)", "default": "18000000000" }, "insight_creative_country_code": { "title": "Country code", "enum": [ "", "US", "JP", "ID", "TH", "MY", "VN", "GB", "FR", "PH", "SA", "ZA", "KR", "ES", "MX" ], "type": "string", "description": "Official country or region filter for Top Ads Insight - Creative Approach. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json)", "default": "" }, "insight_creative_time_range": { "title": "Time range", "enum": [ "7", "30" ], "type": "string", "description": "Publication time range for Top Ads Insight - Creative Approach. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json)", "default": "30" }, "insight_creative_order_field": { "title": "Sort by", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Ranking matrix used by Top Ads Insight - Creative Approach. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json)", "default": "1" }, "insight_selling_industry_label": { "title": "Industry label", "enum": [ "18000000000", "14000000000", "22000000000", "29000000000", "16000000000", "28000000000", "20000000000" ], "type": "string", "description": "Official industry label for Top Ads Insight - Selling Point Analysis. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json)", "default": "18000000000" }, "insight_selling_country_code": { "title": "Country code", "enum": [ "", "US", "JP", "ID", "TH", "MY", "VN", "GB", "FR", "PH", "SA", "ZA", "KR", "ES", "MX" ], "type": "string", "description": "Official country or region filter for Top Ads Insight - Selling Point Analysis. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json)", "default": "" }, "insight_selling_time_range": { "title": "Time range", "enum": [ "7", "30" ], "type": "string", "description": "Publication time range for Top Ads Insight - Selling Point Analysis. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json)", "default": "30" }, "insight_selling_order_field": { "title": "Sort by", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Ranking matrix used by Top Ads Insight - Selling Point Analysis. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json)", "default": "1" }, "insight_top20_industry_label": { "title": "Industry label", "enum": [ "18000000000", "14000000000", "22000000000", "29000000000", "16000000000", "28000000000", "20000000000" ], "type": "string", "description": "Official industry label for Top Ads Insight - Top 20 Selling Points. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json)", "default": "18000000000" }, "insight_top20_country_code": { "title": "Country code", "enum": [ "", "US", "JP", "ID", "TH", "MY", "VN", "GB", "FR", "PH", "SA", "ZA", "KR", "ES", "MX" ], "type": "string", "description": "Official country or region filter for Top Ads Insight - Top 20 Selling Points. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json)", "default": "" }, "insight_top20_time_range": { "title": "Time range", "enum": [ "7", "30" ], "type": "string", "description": "Publication time range for Top Ads Insight - Top 20 Selling Points. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json)", "default": "30" }, "insight_top20_order_field": { "title": "Sort by", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Ranking matrix used by Top Ads Insight - Top 20 Selling Points. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json)", "default": "1" }, "insight_top20_category": { "title": "Category", "type": "string", "description": "Use `SellingPoints[].categoryName` from `Top Ads Insight - Selling Point Analysis`; required by `Top Ads Insight - Top 20 Selling Points`." }, "insight_formula_material_industry_label": { "title": "Industry label", "enum": [ "18000000000", "14000000000", "22000000000", "29000000000", "16000000000", "28000000000", "20000000000" ], "type": "string", "description": "Official industry label for Top Ads Insight - Creative Approach Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json)", "default": "18000000000" }, "insight_formula_material_country_code": { "title": "Country code", "enum": [ "", "US", "JP", "ID", "TH", "MY", "VN", "GB", "FR", "PH", "SA", "ZA", "KR", "ES", "MX" ], "type": "string", "description": "Official country or region filter for Top Ads Insight - Creative Approach Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json)", "default": "" }, "insight_formula_material_time_range": { "title": "Time range", "enum": [ "7", "30" ], "type": "string", "description": "Publication time range for Top Ads Insight - Creative Approach Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json)", "default": "30" }, "insight_formula_material_order_field": { "title": "Sort by", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Ranking matrix used by Top Ads Insight - Creative Approach Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json)", "default": "1" }, "insight_formula_material_formula_id": { "title": "Formula ID", "type": "string", "description": "Use `formulaList[].id` from `Top Ads Insight - Creative Approach`." }, "insight_formula_material_page": { "title": "Page", "minimum": 1, "type": "integer", "description": "Page number for Top Ads Insight - Creative Approach Materials.", "default": 1 }, "insight_formula_material_limit": { "title": "Limit", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Number of Top Ads Insight - Creative Approach Materials records per page.", "default": 20 }, "insight_selling_material_industry_label": { "title": "Industry label", "enum": [ "18000000000", "14000000000", "22000000000", "29000000000", "16000000000", "28000000000", "20000000000" ], "type": "string", "description": "Official industry label for Top Ads Insight - Selling Point Analysis Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_industry.json)", "default": "18000000000" }, "insight_selling_material_country_code": { "title": "Country code", "enum": [ "", "US", "JP", "ID", "TH", "MY", "VN", "GB", "FR", "PH", "SA", "ZA", "KR", "ES", "MX" ], "type": "string", "description": "Official country or region filter for Top Ads Insight - Selling Point Analysis Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_country.json)", "default": "" }, "insight_selling_material_time_range": { "title": "Time range", "enum": [ "7", "30" ], "type": "string", "description": "Publication time range for Top Ads Insight - Selling Point Analysis Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_time_range.json)", "default": "30" }, "insight_selling_material_order_field": { "title": "Sort by", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Ranking matrix used by Top Ads Insight - Selling Point Analysis Materials. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_insight_order_field.json)", "default": "1" }, "insight_selling_material_selling_point": { "title": "Selling point", "type": "string", "description": "Use `SellingPoints[].sellingPointName` from `Top Ads Insight - Top 20 Selling Points`." }, "insight_selling_material_page": { "title": "Page", "minimum": 1, "type": "integer", "description": "Page number for Top Ads Insight - Selling Point Analysis Materials.", "default": 1 }, "insight_selling_material_limit": { "title": "Limit", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Number of Top Ads Insight - Selling Point Analysis Materials records per page.", "default": 20 }, "insight_detail_material_id": { "title": "Insight material ID", "type": "string", "description": "Use `itemList[].materialID` from `Top Ads Insight - Creative Approach Materials` or `Top Ads Insight - Selling Point Analysis Materials`." }, "library_industry_label": { "title": "Industry label", "enum": [ "", "20111000000", "20104000000", "25311000000", "18100000000", "16104000000", "21000000000", "23127000000", "25312000000", "13105000000", "14104000000", "23110000000", "16999000000", "13108000000", "13112000000", "12108000000", "12107000000", "12000000000", "13117000000", "11106000000", "14000000000", "25308000000", "23103000000", "23102000000", "23126000000", "23131000000", "14107000000", "18107000000", "12106000000", "12101000000", "18105000000", "24106000000", "23130000000", "13104000000", "26999000000", "11999000000", "28101000000", "12104000000", "24116000000", "23999000000", "24112000000", "30000000000", "13109000000", "15100000000", "26100000000", "18109000000", "22112000000", "14102000000", "22109000000", "23114000000", "10100000000", "25310000000", "14106000000", "22110000000", "18104000000", "23116000000", "26102000000", "19104000000", "19100000000", "19101000000", "24104000000", "24110000000", "29000000000", "25304000000", "11104000000", "18103000000", "20109000000", "13114000000", "25309000000", "27101000000", "11107000000", "21101000000", "20101000000", "17000000000", "20108000000", "11110000000", "26000000000", "10000000000", "23115000000", "23132000000", "29101000000", "15105000000", "23118000000", "24119000000", "29103000000", "12109000000", "20999000000", "23134000000", "27999000000", "23107000000", "24100000000", "23112000000", "22111000000", "24117000000", "28100000000", "12110000000", "16101000000", "18000000000", "19103000000", "23117000000", "17106000000", "14103000000", "21102000000", "29100000000", "19102000000", "25313000000", "11108000000", "26109000000", "22101000000", "11103000000", "15101000000", "23104000000", "24101000000", "16105000000", "23113000000", "13110000000", "13103000000", "30101000000", "26104000000", "11109000000", "13101000000", "14999000000", "21100000000", "22113000000", "26108000000", "23122000000", "28000000000", "15103000000", "22105000000", "22999000000", "24115000000", "21103000000", "18106000000", "24107000000", "23101000000", "13113000000", "18102000000", "24103000000", "10103000000", "20103000000", "24113000000", "20107000000", "11105000000", "19106000000", "23100000000", "17105000000", "24999000000", "25300000000", "11000000000", "20105000000", "20112000000", "18999000000", "11112000000", "21999000000", "18112000000", "13000000000", "23129000000", "24111000000", "26113000000", "25305000000", "14100000000", "19105000000", "10105000000", "12102000000", "24118000000", "20106000000", "23105000000", "22102000000", "25306000000", "12999000000", "23000000000", "27102000000", "15999000000", "15106000000", "27103000000", "25999000000", "10102000000", "24105000000", "13115000000", "29999000000", "24114000000", "20110000000", "23106000000", "16100000000", "23128000000", "16102000000", "11102000000", "11111000000", "18101000000", "15104000000", "24109000000", "10999000000", "13100000000", "15000000000", "24120000000", "24000000000", "18108000000", "23125000000", "13116000000", "30102000000", "13999000000", "14105000000", "30100000000", "11101000000", "13102000000", "18111000000", "26107000000", "26112000000", "27100000000", "25302000000", "15107000000", "26106000000", "25301000000", "21105000000", "25000000000", "23133000000", "19999000000", "20102000000", "22107000000", "20000000000", "10106000000", "24108000000", "29102000000", "26114000000", "11100000000", "13107000000", "20100000000", "12103000000", "21104000000", "27000000000", "27104000000", "22000000000", "23111000000", "16000000000", "25307000000", "14101000000", "26101000000", "26103000000", "23124000000", "23109000000", "24102000000", "12100000000", "26111000000", "22108000000", "23108000000", "23119000000", "17103000000", "22106000000", "17999000000", "19000000000", "25303000000", "23123000000", "13111000000", "15102000000", "18110000000", "26105000000", "12105000000", "10104000000", "10101000000" ], "type": "string", "description": "Official industry label for Top Ads Library. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_industry.json)", "default": "" }, "library_country_code": { "title": "Country code", "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" ], "type": "string", "description": "Official country or region filter for Top Ads Library. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_country.json)", "default": "" }, "library_time_range": { "title": "Time range", "enum": [ "7", "30", "180" ], "type": "string", "description": "Publication time range for Top Ads Library. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_time_range.json)", "default": "30" }, "library_search_word": { "title": "Search word", "type": "string", "description": "Search by brand, product, or creative keyword." }, "library_objective": { "title": "Objective", "enum": [ "", "1", "2", "3", "4", "5", "8", "15" ], "type": "string", "description": "Campaign objective. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_objective.json)", "default": "" }, "library_like_cnt_filter": { "title": "Likes percentile", "enum": [ "", "1", "2", "3", "4", "5" ], "type": "string", "description": "Like count percentile filter. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_like_cnt_filter.json)", "default": "" }, "library_order_field": { "title": "Sort by", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Metric used to sort Top Ads Library results. [Options](https://raw.githubusercontent.com/lofe-w/tiktok-one-scraper-public/refs/heads/main/options/top_ads_library_order_field.json)", "default": "1" }, "library_page": { "title": "Page", "minimum": 1, "type": "integer", "description": "Page number for Top Ads Library results.", "default": 1 }, "library_limit": { "title": "Limit", "minimum": 1, "maximum": 50, "type": "integer", "description": "Number of Top Ads Library records per page.", "default": 20 }, "library_material_id": { "title": "Material ID", "type": "string", "description": "Use `itemList[].materialID` from `Top Ads Library`." } } }, "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 } } } } } } } } } } ```