{ "openapi": "3.0.1", "info": { "title": "TikTok Shop Scraper | Fast Search & Full Product Data", "description": "Scrape TikTok Shop US with fast keyword search or full product details, including reviews, SKUs, stock and shipping. Collect category products from 9 more markets with local prices, currencies, sales and seller data. Includes pagination, filters, sorting and deduplication.", "version": "0.2", "x-build-id": "hJwSOvmdiRyDFc5Ud" }, "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/Full search US products. Full by URL/ID collects specified US products directly. Regional Search supports SG, MY, TH, VN and PH; Regional Catalog supports all nine local stores. Full details and review texts remain US-only.", "default": "fast" }, "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 or Catalog. GB, ID, MX, JP: Regional Catalog. Direct Full is not enabled for other countries; no US results are relabeled as regional products.", "default": "US" }, "productUrls": { "title": "๐Ÿ”— US product URLs", "type": "array", "description": "Full by URL/ID only. Paste direct US TikTok Shop /view/product/ or /pdp/ links, one per entry. Combine with productIds if needed. Video, profile, store, category and shortened links are not accepted. Choose mode=product_details explicitly; other modes will not silently fetch these products.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "productIds": { "title": "๐Ÿ†” US 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. At least one URL or ID is required. Duplicate IDs across both lists are removed when dedupe is enabled. Maximum 1000 combined inputs.", "items": { "type": "string" }, "default": [] }, "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" ] }, "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" }, "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 }, "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 }, "freeShippingOnly": { "title": "๐Ÿšš Free shipping only", "type": "boolean", "description": "Keep only products where TikTok includes a free-shipping tag or shipping field.", "default": false }, "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 }, "includeReviews": { "title": "โญ Include customer reviews", "type": "boolean", "description": "Full search and Full by URL/ID only. Attach complete public review objects. The first 5 reviews are included in the Full result price; higher limits can use a separate review event once active.", "default": true }, "maxReviews": { "title": "Reviews per product", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Full search and Full by URL/ID only. Maximum reviews to attach per product. Use 0 to request all reviews exposed by TikTok.", "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 }, "page": { "title": "Start page", "minimum": 1, "maximum": 100, "type": "integer", "description": "First search results page to fetch.", "default": 1 }, "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 } } }, "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 } } } } } } } } } }