{ "openapi": "3.0.1", "info": { "title": "TikTok Shop Reviews Scraper", "description": "Scrape public TikTok Shop product reviews in bulk: star rating, text, date, photos, purchased variant, verified/incentivized flags, reviewer context and product rating data. Monitor new reviews with date and skip-ID controls. No TikTok login.", "version": "1.0", "x-build-id": "tAYiJWS8EL3N8FZYF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/coregent~tiktok-shop-reviews-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-coregent-tiktok-shop-reviews-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/coregent~tiktok-shop-reviews-scraper/runs": { "post": { "operationId": "runs-sync-coregent-tiktok-shop-reviews-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/coregent~tiktok-shop-reviews-scraper/run-sync": { "post": { "operationId": "run-sync-coregent-tiktok-shop-reviews-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": [ "productTargets" ], "properties": { "productTargets": { "title": "Products", "minItems": 1, "maxItems": 500, "type": "array", "description": "TikTok Shop product URLs or numeric product IDs (1–500). Accepted: tiktok.com/shop/pdp//, shop.tiktok.com//pdp//, tiktok.com/view/product/, or the bare ID. Duplicates are merged before any work is done.", "default": [ "1731649211243074211" ], "items": { "type": "string" } }, "region": { "title": "Region (storefront)", "enum": [ "US", "MY", "TH", "VN", "PH", "SG" ], "type": "string", "description": "Storefront used for bare product IDs. A region in the product URL (e.g. shop.tiktok.com/my/pdp/…) takes precedence. Only storefronts we have tested are listed.", "default": "US" }, "maxReviewsPerProduct": { "title": "Max reviews per product", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum reviews delivered (and charged) per product. Reviews arrive 20 per page.", "default": 20 }, "maxTotalReviews": { "title": "Max total reviews", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Run-wide ceiling on unique reviews delivered across all products. The run stops exactly here — your cost ceiling.", "default": 1000 }, "sortBy": { "title": "Review order", "enum": [ "recommended", "newest" ], "type": "string", "description": "Order in which TikTok returns reviews. Forced to Newest when 'Reviews published after' is set.", "default": "recommended" }, "starRating": { "title": "Star rating", "minimum": 0, "maximum": 5, "type": "integer", "description": "0 = all ratings; 1–5 = only reviews with exactly that many stars (filtered by TikTok, so it does not waste scans).", "default": 0 }, "mediaOnly": { "title": "Only reviews with photos", "type": "boolean", "description": "Keep only reviews with publicly exposed photo URLs. Video-only reviews are dropped because TikTok does not expose their media URLs.", "default": false }, "verifiedPurchaseOnly": { "title": "Only verified purchases", "type": "boolean", "description": "Keep only reviews TikTok marks as verified purchases.", "default": false }, "publishedAfter": { "title": "Reviews published after", "type": "string", "description": "Keep reviews at or after this date: ISO (2026-10-01) or relative (24h, 7d, 2w, 3m). Enables cheap new-review monitoring: the scan stops as soon as it passes the boundary.", "default": "" }, "publishedBefore": { "title": "Reviews published before", "type": "string", "description": "Optional upper date boundary (ISO or relative).", "default": "" }, "skipReviewIds": { "title": "Skip review IDs", "type": "array", "description": "Review IDs you already have. They are skipped before output and are never charged.", "default": [], "items": { "type": "string" } }, "incentivizedOnly": { "title": "Only incentivized reviews", "type": "boolean", "description": "Keep only reviews TikTok flags as incentivized/rewarded. Applied after fetching, so restrictive use can return fewer rows than requested (filtered rows are free).", "default": false }, "includeProductContext": { "title": "Include product context", "type": "boolean", "description": "Attach product title, image, shop, currency, overall rating and total review count to every row (fetched once per product, free).", "default": true }, "includeRatingBreakdown": { "title": "Include 1–5 star breakdown", "type": "boolean", "description": "Add the product's rating1Count … rating5Count distribution to each row.", "default": true }, "includeReviewerContext": { "title": "Include reviewer context", "type": "boolean", "description": "Public reviewer fields as TikTok shows them (masked display name, reviewer ID, avatar, country). Nothing is unmasked or enriched.", "default": true }, "includeMedia": { "title": "Include review photo URLs", "type": "boolean", "description": "Include the media array with review photo URLs. mediaCount and hasMedia are always included.", "default": true }, "maxPagesPerProduct": { "title": "Max pages per product", "minimum": 1, "maximum": 500, "type": "integer", "description": "Scan guard (20 reviews per page). Stops pathological deep scans when filters match few reviews.", "default": 250 }, "maxNoMatchPages": { "title": "Max pages without a match", "minimum": 0, "maximum": 250, "type": "integer", "description": "Stop scanning a product after this many pages in a row that deliver no review (all filtered out, skipped or duplicates). Keeps rarely matching filters from scanning deep for nothing. Pages skipped only for being newer than 'Reviews published before' do not count. 0 = off.", "default": 10 }, "maxRetries": { "title": "Max retries", "minimum": 0, "maximum": 5, "type": "integer", "description": "Retries per request on transient source failures (throttling, 5xx).", "default": 2 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 4, "type": "integer", "description": "Products processed in parallel (clamped to 1–4).", "default": 3 }, "debugMode": { "title": "Debug logging", "type": "boolean", "description": "Verbose logs (retries, request details). Secrets are never logged.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "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 } } } } } } } } } }