{ "openapi": "3.0.1", "info": { "title": "TikTok Shop Scraper API โ€” Products, Reviews & Sellers", "description": "Scrape TikTok Shop products with full detail in all 10 stores: descriptions, SKUs, stock, shipping, videos and customer reviews. Search by keyword in the US and 5 regional stores, browse category catalogs in 9 markets, or pull exact products by URL or ID. Local prices, never converted.", "version": "0.2", "x-build-id": "L8u9sQk5DV8O24bhQ" }, "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": "๐ŸŽฏ Mode", "enum": [ "fast", "full", "product_details", "regional_search", "regional_catalog" ], "type": "string", "description": "Fast and Full search US products. Full by URL/ID collects specified products from any of the ten stores. Regional Search finds products by name in five stores; Regional Catalog browses categories in nine. Both regional modes can attach full product data and reviews by setting mode to Full.", "default": "fast" }, "keywords": { "title": "๐Ÿ” Product name, brand or keyword(s)", "type": "array", "description": "For Fast, Full or Regional Search. Enter ONE search phrase per list entry, for example separate entries for lipstick and phone case. Commas inside an entry are literal and are not split into more searches. Regional Search also requires matching terms in the title; use local-language names where appropriate. Regional Catalog uses a category instead.", "items": { "type": "string" }, "default": [ "water bottle" ] }, "productUrls": { "title": "๐Ÿ”— Product URLs", "type": "array", "description": "Full by URL/ID only. Paste TikTok Shop /view/product/ or /pdp/ links from the store you selected, one per entry โ€” every one of the ten stores is supported. Combine with productIds if needed. Video, profile, store and category links are not product inputs.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "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": [] }, "region": { "title": "๐ŸŒ Store country / currency", "enum": [ "US", "GB", "SG", "MY", "TH", "VN", "PH", "ID", "MX", "JP" ], "type": "string", "description": "US: Fast, Full search or Full by URL/ID. SG, MY, TH, VN, PH: Regional Search, Catalog and Full by URL/ID. GB, ID, MX, JP: Catalog and Full by URL/ID. Every store supports full product data and reviews. Prices are never converted; the UK store hides price digits, and those rows say priceStatus=masked_by_storefront.", "default": "US" }, "regionalSearchMatch": { "title": "๐ŸŽฏ Regional Search title matching", "enum": [ "all_terms", "phrase" ], "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" }, "regionalCategory": { "title": "๐Ÿ›๏ธ Regional category", "enum": [ "beauty", "home", "womenswear" ], "type": "string", "description": "Regional Catalog only. Select a ready-to-use category, or override it with your own category URLs below.", "default": "beauty" }, "regionalUrls": { "title": "๐Ÿ”— Custom regional category URLs (optional)", "type": "array", "description": "Regional Catalog only. Optional /c/ category URLs from the selected country, for example https://shop.tiktok.com/gb/c/beauty-personal-care/601450. These replace the preset category. Leave empty to use the dropdown.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "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": [] }, "maxItems": { "title": "๐Ÿ’ฏ Maximum products", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Maximum saved products per keyword in US search modes, or total across direct product inputs and regional modes. Filtered products and duplicates (when dedupe is enabled) do not consume the allowance. Direct product failures do not create paid placeholder rows. Set 0 for no explicit item cap.", "default": 10 }, "maxPages": { "title": "๐Ÿ“„ Pages per query / category", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum pages per query/category, when TikTok supplies continuation. Catalog pages typically contain 15โ€“20 products; use at least 4 for 50 catalog products. Regional Search may expose a short, single-page feed; add several queries for a broader batch.", "default": 1 }, "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" }, "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" } }, "includeReviews": { "title": "โญ Include customer reviews", "type": "boolean", "description": "Full modes only, in every store. Attach complete public review objects. The first 5 reviews are included in the Full result price; higher limits cost extra per review. Outside the US the reviews come from the product page, which carries the newest ones.", "default": true }, "maxReviews": { "title": "Reviews per product", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Full modes only. Maximum reviews to attach per product. Use 0 to request all reviews exposed by TikTok. Outside the US the product page supplies the newest reviews, so a high limit returns what that page carries.", "default": 5 }, "reviewSort": { "title": "Review order", "enum": [ "recommended", "recent" ], "type": "string", "description": "Full search and Full by URL/ID only. Use TikTok's recommended order or newest reviews first.", "default": "recommended" }, "trackChanges": { "title": "๐Ÿ“ˆ Track price, sales, and stock changes", "type": "boolean", "description": "Full search and Full by URL/ID only. Save a private product snapshot and calculate sold velocity, price changes, and stock movement from the second run onward.", "default": false }, "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 } } }, "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 } } } } } } } } } }