{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Shop Scraper: Products, Reviews, Sellers & Keyword Rank",
    "description": "Track TikTok Shop prices, ratings, reviews, sellers and keyword rank. Paste product URLs, a seller id or keywords and get clean rows back. Five modes in one actor, and keyword results are scored against your keyword before billing, so you never pay for products that do not match.",
    "version": "0.0",
    "x-build-id": "hxMNdgchFVwFhsr9E"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sourabhbgp~tiktok-shop-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sourabhbgp-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/sourabhbgp~tiktok-shop-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sourabhbgp-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/sourabhbgp~tiktok-shop-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sourabhbgp-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": "What to scrape",
            "enum": [
              "products",
              "seller",
              "reviews",
              "search",
              "category"
            ],
            "type": "string",
            "description": "Pick one job per run. Products: track price, rating, review count and units sold for a list of products. Seller: pull a shop's whole catalogue. Reviews: pull review text and the star histogram for a product. Search: see which products rank for a keyword. Category: list products in a category.",
            "default": "products"
          },
          "productUrls": {
            "title": "Product URLs or ids",
            "type": "array",
            "description": "Used by the Products and Reviews modes. Paste TikTok Shop product URLs or bare numeric product ids. The slug in a product URL is decorative, so a bare id works just as well.",
            "items": {
              "type": "string"
            }
          },
          "maxReviewsPerProduct": {
            "title": "Max reviews per product",
            "minimum": 1,
            "maximum": 20000,
            "type": "integer",
            "description": "Reviews mode only. A popular product can carry thousands of reviews, so this cap exists to stop one product id turning into a bill you did not expect. Raise it when you want a complete set. The run log says which products still had more reviews available when the cap was reached.",
            "default": 500
          },
          "reviewSort": {
            "title": "Review order",
            "enum": [
              "recommended",
              "recent"
            ],
            "type": "string",
            "description": "Reviews mode only.",
            "default": "recommended"
          },
          "reviewStarFilter": {
            "title": "Only this star rating",
            "enum": [
              "all",
              "1",
              "2",
              "3",
              "4",
              "5"
            ],
            "type": "string",
            "description": "Reviews mode only. Keep it on All unless you want, for example, only the 1 star reviews.",
            "default": "all"
          },
          "reviewsWithMediaOnly": {
            "title": "Only reviews with photos or video",
            "type": "boolean",
            "description": "Reviews mode only. Overrides the star filter when switched on.",
            "default": false
          },
          "sellerUrls": {
            "title": "Seller ids",
            "type": "array",
            "description": "Seller mode only. A numeric seller id, or any TikTok Shop URL containing one. Every product row carries sellerId, so you can take an id straight from an earlier run.",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "title": "Search keywords",
            "type": "array",
            "description": "Search mode only. One keyword per line. Each result row carries its rank position for that keyword, so repeated runs give you rank over time.",
            "items": {
              "type": "string"
            }
          },
          "searchDepth": {
            "title": "Results to request per keyword",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Search mode only. TikTok Shop returns keyword results in a single shot with no pagination, so this is the whole depth available. 200 is the maximum that returns data.",
            "default": 100
          },
          "minRelevance": {
            "title": "Minimum keyword relevance",
            "enum": [
              "0.33",
              "0.5",
              "0.75",
              "1"
            ],
            "type": "string",
            "description": "Search mode only. TikTok Shop pads keyword results with unrelated products, even for keywords that match nothing at all. Each result is scored on how much of your keyword appears in the product title and brand, and anything below this score is dropped and never billed. 0.5 means at least half your keyword terms must appear.",
            "default": "0.5"
          },
          "includeIrrelevant": {
            "title": "Also return the results that were filtered out",
            "type": "boolean",
            "description": "Search mode only. Off by default, so you are not billed for padding. Switch on to see everything TikTok Shop returned, each row flagged with isRelevant and relevanceScore. Note that these rows are billed.",
            "default": false
          },
          "categoryUrls": {
            "title": "Category URLs",
            "type": "array",
            "description": "Category mode only. A TikTok Shop category page URL (it contains /c/).",
            "items": {
              "type": "string"
            }
          },
          "region": {
            "title": "Storefront",
            "enum": [
              "us",
              "gb"
            ],
            "type": "string",
            "description": "The US storefront supports every mode. The UK storefront supports the Category mode only.",
            "default": "us"
          },
          "maxItems": {
            "title": "Max rows",
            "minimum": 1,
            "type": "integer",
            "description": "Hard stop on rows delivered and billed. Leave empty for no limit."
          },
          "includeSkus": {
            "title": "Include a per variant price breakdown",
            "type": "boolean",
            "description": "Adds a skus array to each product row with the price of every variant. Off by default because it makes rows considerably larger.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "TikTok Shop serves a security check to unproxied requests, so a proxy is required. The default routes through datacenter proxy and escalates to residential automatically if datacenter is refused.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}