{ "openapi": "3.0.1", "info": { "title": "TikTok Shop Scraper API โ€” Products, Reviews & Sellers", "description": "Collect the official TikTok Shop US product feed without keywords, or search products and collect details, SKUs, stock, shipping, videos and reviews. Regional catalogs and direct product inputs remain supported.", "version": "0.2", "x-build-id": "KTCqwwFxFvBNv9hYU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/trakk~tiktok-shop-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-trakk-tiktok-shop-search-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/trakk~tiktok-shop-search-scraper/runs": { "post": { "operationId": "runs-sync-trakk-tiktok-shop-search-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/trakk~tiktok-shop-search-scraper/run-sync": { "post": { "operationId": "run-sync-trakk-tiktok-shop-search-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": { "mode": { "title": "โšก Scraping mode", "enum": [ "fast", "full" ], "type": "string", "description": "Fast collects product cards. Full adds all available descriptions, variants, stock, delivery, media, business details and optional reviews. Both modes work with every listed store.", "default": "fast" }, "region": { "title": "๐ŸŒ Store", "enum": [ "US", "GB", "SG", "MY", "TH", "VN", "PH", "ID", "MX", "JP" ], "type": "string", "description": "Choose the TikTok Shop store for either Fast or Full. With no query or links: US/UK use the official public feed; other stores browse their local category catalog. Prices keep the selected store currency.", "default": "US" }, "maxItems": { "title": "๐Ÿ“Š Maximum products", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Maximum saved products in total for Official Shop feed, direct product inputs and regional modes; per keyword for US search. Filtered products, failed writes and enabled deduplication do not consume this allowance. 0 means no explicit saved-product cap.", "default": 10 }, "keywords": { "title": "๐Ÿ”Ž Search keywords", "type": "array", "description": "Optional: one search phrase per entry. US, SG, MY, TH, VN and PH use keyword search. Other stores apply these words to the selected category catalog. Leave empty to browse the default source.", "items": { "type": "string" }, "default": [] }, "productUrls": { "title": "๐Ÿ”— Product URLs or IDs", "type": "array", "description": "Optional in Fast or Full: one TikTok Shop product URL or quoted product ID per entry. Fast returns the product card; Full adds available details and reviews. Links must match the selected store.", "default": [], "items": { "type": "string" } }, "regionalCategory": { "title": "๐Ÿ—‚๏ธ Catalog category", "enum": [ "beauty", "home", "womenswear" ], "type": "string", "description": "Category for local catalog sources. US/UK default discovery uses their official feed, where this category setting is inactive.", "default": "beauty" }, "regionalUrls": { "title": "Category URLs (optional)", "type": "array", "description": "Optional non-US /c/ category links from the selected store. These replace the category preset and select catalog browsing in either mode.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "feedCollection": { "title": "๐Ÿ›๏ธ Feed collection", "enum": [ "auto", "recommended_for_you", "all", "top_selling", "discounted", "selling_point", "shop_guide", "black_friday" ], "type": "string", "description": "Optional for automatic US/UK feed discovery. Store default chooses the US recommendation feed or available UK collections. Inactive for search, catalog and product links." }, "fullData": { "title": "๐Ÿ“ฆ Add full product data", "type": "boolean", "description": "Feed and regional modes: add all available descriptions, variants, stock, shipping, media and seller details. Full search and Product details already include full data.", "default": false }, "includeReviews": { "title": "โญ Include customer reviews", "type": "boolean", "description": "Full only. Include the public reviews made available by TikTok. Up to five reviews are included with each successful Full result; additional collected reviews use the existing review price.", "default": true }, "maxReviews": { "title": "Reviews per product", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Full only: maximum public reviews per product. 0 requests all exposed reviews. The source can provide fewer than the requested limit.", "default": 5 }, "maxPages": { "title": "Pages per search / category", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum pages per search, category or feed collection, subject to source continuation. Product links do not use pages.", "default": 3 }, "sortBy": { "title": "โ†•๏ธ Sort products by", "enum": [ "relevance", "best_sellers", "price_asc", "price_desc", "rating_desc" ], "type": "string", "description": "Local sort, not a store-wide ranking. Full by URL/ID sorts all successfully fetched matching inputs before applying maxItems; relevance streams completed records. Existing search/catalog sorting applies to their collected candidate sets.", "default": "relevance" }, "trackChanges": { "title": "๐Ÿ“ˆ Track price, sales, and stock changes", "type": "boolean", "description": "Full search and Product details only. Compare price, sales and stock with a previous saved snapshot. The first run creates the baseline.", "default": false }, "productIds": { "title": "๐Ÿ†” Product IDs", "type": "array", "description": "Full by URL/ID only. Enter 15-22 digit TikTok Shop product IDs as strings, not video or seller IDs. They are read from the store chosen in region. At least one URL or ID is required. Duplicate IDs are collected once.", "items": { "type": "string" }, "default": [] }, "homepageGroups": { "title": "๐Ÿ›๏ธ Official feed collections", "type": "array", "description": "Official Shop feed only. recommended_for_you is the public recommendation feed. An empty list collects all supported component groups. Named groups: recommended_for_you, top_selling, discounted, selling_point, shop_guide, black_friday. Other groups: component_8, component_14, component_15, component_18, component_20, component_21, component_22, component_23. Availability varies by store and session; use named for the six named groups.", "items": { "type": "string" }, "default": [] }, "homepageMaxPages": { "title": "๐Ÿ“„ Pages per feed collection", "minimum": 1, "maximum": 200, "type": "integer", "description": "Official Shop feed only. Maximum source pages per collection. The run continues through new product IDs until this limit, the saved-product limit, the spending limit, or no progress. Page size and continuation depend on TikTok." }, "homepageMaxItemsPerGroup": { "title": "๐Ÿ’ฏ Maximum saved products per collection", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Homepage Hot mode only. Optional cap per rail so one deep rail does not use the whole Maximum products budget. 0 = no per-rail cap.", "default": 0 }, "regionalSearchMatch": { "title": "๐ŸŽฏ Regional Search title matching", "type": "string", "description": "Regional Search only. All terms keeps titles containing every search term, in any order. Phrase keeps the phrase together. Case and punctuation are normalized; names are not translated. Unrelated recommendations are discarded before saving.", "default": "all_terms" }, "regionalFilterKeywords": { "title": "๐Ÿ”Ž Regional title filter (optional)", "type": "array", "description": "Regional Catalog only. Keep collected products whose titles contain at least one phrase. This filters the chosen category locally; it is not a keyword search across the store. Use local-language terms where appropriate.", "items": { "type": "string" }, "default": [] }, "page": { "title": "Start page", "minimum": 1, "maximum": 100, "type": "integer", "description": "First search results page to fetch.", "default": 1 }, "minPrice": { "title": "Minimum price", "type": "number", "description": "Optional local filter on normalized currentPrice." }, "maxPrice": { "title": "Maximum price", "type": "number", "description": "Optional local filter on normalized currentPrice." }, "minRating": { "title": "Minimum rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Keep only products at or above this rating when rating is available.", "default": 0 }, "maxRating": { "title": "โ˜… Maximum rating", "minimum": 1, "maximum": 5, "type": "integer", "description": "Keep only products rated at or below this (1โ€“5). Combine with minRating to isolate a band." }, "minReviewCount": { "title": "Minimum reviews", "minimum": 0, "type": "integer", "description": "Keep only products with at least this many reviews.", "default": 0 }, "minSoldCount": { "title": "Minimum sold count", "minimum": 0, "type": "integer", "description": "Keep only products at or above this sold count when soldCount is available.", "default": 0 }, "maxSoldCount": { "title": "Maximum units sold", "minimum": 0, "type": "integer", "description": "Keep only products with at most this many units sold (find newer / less saturated products).", "default": 0 }, "freeShippingOnly": { "title": "๐Ÿšš Free shipping only", "type": "boolean", "description": "Keep only products where TikTok includes a free-shipping tag or shipping field.", "default": false }, "onlyDiscounted": { "title": "๐Ÿ’ธ Only discounted", "type": "boolean", "description": "Keep only products currently priced below their original price.", "default": false }, "minDiscountPercent": { "title": "Minimum discount %", "minimum": 0, "maximum": 100, "type": "integer", "description": "Keep only products discounted by at least this percentage." }, "titleKeywords": { "title": "Title must contain", "type": "array", "description": "Keep only products whose title contains one of these words.", "items": { "type": "string" } }, "excludeKeywords": { "title": "Exclude words", "type": "array", "description": "Drop products whose title or tags contain any of these words.", "items": { "type": "string" } }, "sellers": { "title": "Only these sellers", "type": "array", "description": "Keep only products from sellers whose name contains one of these.", "items": { "type": "string" } }, "excludeSellers": { "title": "Exclude sellers", "type": "array", "description": "Drop products from sellers whose name contains one of these.", "items": { "type": "string" } }, "reviewSort": { "title": "Review order", "type": "string", "description": "Full search and Full by URL/ID only. Use TikTok's recommended order or newest reviews first.", "default": "recommended" }, "includeRawDetail": { "title": "Include raw full-detail payload", "type": "boolean", "description": "Full search and Full by URL/ID only. Store the complete product-detail API response in rawDetailJson. Enable for debugging because rows become much larger.", "default": false }, "fullConcurrency": { "title": "Full-detail concurrency", "minimum": 1, "maximum": 12, "type": "integer", "description": "Full search and Full by URL/ID only. Number of products enriched in parallel. Higher is faster; lower it if you hit blocks.", "default": 8 }, "detailTimeoutSec": { "title": "Full-detail timeout", "minimum": 5, "maximum": 120, "type": "integer", "description": "Full search and Full by URL/ID only. Timeout for each product-detail or review request.", "default": 18 }, "detailMaxRetries": { "title": "Full-detail retries", "minimum": 0, "maximum": 10, "type": "integer", "description": "Full search and Full by URL/ID only. Additional attempts with a fresh proxy when a product detail request is blocked or temporarily unavailable.", "default": 2 }, "dedupe": { "title": "Deduplicate products globally", "type": "boolean", "description": "Avoid pushing the same product multiple times when it appears for multiple keywords or pages.", "default": true }, "compactOutput": { "title": "๐Ÿงน Compact output", "type": "boolean", "description": "Remove null, empty array, and empty object values from output items.", "default": true }, "includeRawProduct": { "title": "Include raw product card", "type": "boolean", "description": "Attach the original TikTok product card as a JSON string in rawProductJson. Usually only needed for debugging.", "default": false }, "htmlReport": { "title": "๐Ÿ–ผ๏ธ Visual HTML report", "type": "boolean", "description": "Build a shareable product-grid report and save it to the key-value store (open the 'report' record after the run). Turn off to skip it.", "default": true }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many keywords to process in parallel.", "default": 1 }, "requestTimeoutSec": { "title": "Request timeout", "minimum": 5, "maximum": 120, "type": "integer", "description": "HTTP request timeout.", "default": 20 }, "maxRetries": { "title": "Max retries per page", "minimum": 0, "maximum": 15, "type": "integer", "description": "Retries on 429/5xx, captcha/security pages, and parse failures.", "default": 2 }, "maxProxyRetries": { "title": "Max proxy retries per page", "minimum": 1, "maximum": 15, "type": "integer", "description": "Dedicated retry budget for proxy / transport failures.", "default": 2 }, "requestDelayMs": { "title": "Delay between pages", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Optional pause between pages for the same keyword.", "default": 0 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "The default proxy is aligned with the selected country. Explicit custom proxy settings are respected.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "country_code": { "title": "Legacy API country code", "type": "string", "description": "Hidden compatibility field for existing API clients. Fast / Full supports US; regional_catalog supports the listed regional markets. Invalid combinations finish safely with a correction message.", "default": "" }, "countryCode": { "title": "Legacy camelCase country code", "type": "string", "description": "Hidden compatibility field for existing API clients.", "default": "" }, "keyword": { "title": "Legacy single keyword", "type": "string", "description": "Hidden compatibility field for users of the original simple keyword input.", "default": "" }, "limit": { "title": "Legacy limit", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hidden compatibility field. maxItems is used by the current UI.", "default": 1 }, "workflow": { "title": "Advanced source override", "type": "string", "description": "JSON/API only: auto, us_search, homepage, regional_search, regional_catalog or product_details. mode still controls Fast versus Full.", "default": "auto" } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }