{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Shop Scraper - Products, Prices, Sales & Reviews",
    "description": "Scrape TikTok Shop by keyword, category or product URL. Extract prices, discounts, sales, ratings, images, shops, variants and reviews. Optional details include descriptions and rating breakdowns. Supports incremental monitoring.",
    "version": "0.1",
    "x-build-id": "xfPs7mJDobrE5VTAD"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/abotapi~tiktok-shop-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-abotapi-tiktok-shop-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/abotapi~tiktok-shop-scraper/runs": {
      "post": {
        "operationId": "runs-sync-abotapi-tiktok-shop-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/abotapi~tiktok-shop-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-abotapi-tiktok-shop-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": [
          "mode"
        ],
        "properties": {
          "mode": {
            "title": "Mode",
            "enum": [
              "category",
              "all",
              "search",
              "product"
            ],
            "type": "string",
            "description": "Choose 'category' to scrape a category and its subcategories, 'all' to walk every category in the store, 'search' for keyword search (top 25-40 results per keyword), or 'product' to scrape direct product links.",
            "default": "category"
          },
          "categoryUrls": {
            "title": "Category links",
            "type": "array",
            "description": "TikTok Shop links to scrape in category mode. Each link is routed by its shape: a category page (/us/c/<name>/<number>, optionally ?page=N to start at that page), a product page (/pdp/...) or a keyword search page (/us/s?q=...). Left untouched, one example of each shape is scraped. Other links are skipped with a warning.",
            "default": [
              "https://shop.tiktok.com/us/c/cases-screen-protectors-stickers/601925",
              "https://shop.tiktok.com/us/c/audio-video/909320",
              "https://shop.tiktok.com/us/c/cases-screen-protectors-stickers/601925?page=2",
              "https://shop.tiktok.com/us/s?q=phone+case",
              "https://shop.tiktok.com/us/pdp/cosrx/1731369897578565803"
            ],
            "items": {
              "type": "string"
            }
          },
          "includeSubcategories": {
            "title": "Include subcategories",
            "type": "boolean",
            "description": "Category mode: when a link points to a parent category, walk every subcategory under it. A parent category page alone shows only about 80 listings; its subcategories together reach far more. Turn off to scrape only the listings shown on the linked page itself.",
            "default": true
          },
          "queries": {
            "title": "Search keywords",
            "type": "array",
            "description": "One or more keywords to search on TikTok Shop, for example 'phone case' or 'yoga leggings'. Each keyword is searched separately and returns the top results TikTok Shop shows for it (25-40 per keyword).",
            "default": [
              "phone case"
            ],
            "items": {
              "type": "string"
            }
          },
          "productUrls": {
            "title": "Product links",
            "type": "array",
            "description": "TikTok Shop product links to scrape in product mode, for example https://shop.tiktok.com/us/pdp/cosrx/1731369897578565803 (also the id-only /us/pdp/<id>, www.tiktok.com/shop/pdp/... and the shared /view/product/<id>?region=US forms). Left untouched, the four example forms are scraped. Category and search links pasted here are routed to their own handlers.",
            "default": [
              "https://shop.tiktok.com/us/pdp/cosrx/1731369897578565803",
              "https://shop.tiktok.com/us/pdp/1732417051041435718",
              "https://shop.tiktok.com/us/pdp/1731845743813890854?utm_source=x&sku_id=1",
              "https://www.tiktok.com/view/product/1729407118584156350",
              "https://www.tiktok.com/shop/pdp/cosrx/1731369897578565803",
              "https://shop.tiktok.com/view/product/1732406648548856677?region=US&locale=en"
            ],
            "items": {
              "type": "string"
            }
          },
          "maxItems": {
            "title": "Max listings",
            "minimum": 0,
            "maximum": 1000000,
            "type": "integer",
            "description": "Maximum number of listings to return across the whole run. This is the run's cap. Use 0 for unlimited (in 'all' mode, unlimited walks the entire store, which can take many hours).",
            "default": 10
          },
          "maxPages": {
            "title": "Max pages (optional)",
            "minimum": 0,
            "type": "integer",
            "description": "Optional extra limit on how many result pages are loaded per category (each page adds about 10-20 listings). Leave empty or 0 — it does not cap anything on its own and defers to Max listings.",
            "default": 0
          },
          "fetchDetails": {
            "title": "Fetch product details",
            "type": "boolean",
            "description": "Open each listing's product page and extract the full detail: description, variations, rating breakdown and item-level reviews. Turn off for a faster, lighter run that returns only the listing-card fields.",
            "default": true
          },
          "includeReviews": {
            "title": "Include item reviews",
            "type": "boolean",
            "description": "Nest each listing's item-level reviews under its row, in addition to the aggregate rating and review count. Requires Fetch product details. Turn off if you only want the listing fields.",
            "default": true
          },
          "maxReviewsPerProduct": {
            "title": "Max reviews per product",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "Keep at most this many reviews under each listing. Applies when Include item reviews is on.",
            "default": 20
          },
          "proxy": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify Proxy connection settings. A residential exit in a supported market is used by default."
          },
          "resumeFromRunId": {
            "title": "Resume from a previous run",
            "type": "string",
            "description": "Paste a previous run or dataset id to skip listings already collected there and return only the rest."
          },
          "incrementalMode": {
            "title": "Incremental mode",
            "type": "boolean",
            "description": "Turn on for scheduled monitoring: later runs return only new and changed listings. Unchanged listings are suppressed and not billed.",
            "default": false
          },
          "stateKey": {
            "title": "State key",
            "type": "string",
            "description": "Optional name for this monitoring campaign's saved state. Use different keys to monitor different searches independently."
          },
          "emitUnchanged": {
            "title": "Emit unchanged listings",
            "type": "boolean",
            "description": "Incremental mode only. Also return, and bill, listings unchanged since the last run.",
            "default": false
          },
          "emitExpired": {
            "title": "Emit expired listings",
            "type": "boolean",
            "description": "Incremental mode only. Also return, and bill, listings no longer found once a run has fully scanned the tracked search.",
            "default": false
          },
          "ignoreFieldsForChanges": {
            "title": "Ignore fields when detecting changes (incremental mode only)",
            "type": "array",
            "description": "Output field names that should NOT make a listing count as UPDATED. images is always ignored, because TikTok Shop re-renders listing image lists with unstable ordering between loads; added or removed photos still change the listing through other fields. Add fields such as description or soldCount here if changes to them are not relevant to you. Ignored fields are still returned in the output.",
            "items": {
              "type": "string"
            }
          },
          "mcpConnectors": {
            "title": "Pipe results into your apps (optional)",
            "type": "array",
            "description": "Optionally send results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize one under Apify, Settings, API & Integrations, then select it here. Notion gets a rich page-per-item export; other connectors get a best-effort write or digest. Leave empty to skip; never changes the dataset output.",
            "items": {
              "type": "string"
            }
          },
          "notionParentPageUrl": {
            "title": "Notion parent page (Notion connector only)",
            "type": "string",
            "description": "URL or id of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors."
          },
          "maxNotifyListings": {
            "title": "Max items to export per connector",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Cap on items written to each connector per run. Does not affect the dataset.",
            "default": 50
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}