{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Shop USA Scraper: Products, Shops, Creators",
    "description": "Scrape TikTok Shop US data by URL, product ID, shop, or creator handle: product detail with price, rating, sold count and variants, shop profiles, creator showcase catalogs, and per-video engagement stats for shoppable videos. One run, one normalized dataset, four entity types.",
    "version": "0.3",
    "x-build-id": "zrt80zvfBFK2EIuzO"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/capable_cauldron~tiktok-shop-usa-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-capable_cauldron-tiktok-shop-usa-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/capable_cauldron~tiktok-shop-usa-scraper/runs": {
      "post": {
        "operationId": "runs-sync-capable_cauldron-tiktok-shop-usa-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/capable_cauldron~tiktok-shop-usa-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-capable_cauldron-tiktok-shop-usa-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": {
          "productUrls": {
            "title": "Product URLs or IDs",
            "type": "array",
            "description": "TikTok Shop product pages to scrape. Accepts any product URL shape (shop.tiktok.com/us/pdp/..., www.tiktok.com/shop/pdp/..., shop.tiktok.com/view/product/...) or a bare product ID like 1731194857673101831.",
            "items": {
              "type": "string"
            }
          },
          "shopUrls": {
            "title": "Shop URLs or seller IDs",
            "type": "array",
            "description": "Storefronts to scrape, as shop.tiktok.com/us/store/<name>/<sellerId> URLs or bare seller IDs. Each one returns a shop profile row plus its product catalog.",
            "items": {
              "type": "string"
            }
          },
          "categoryUrls": {
            "title": "Category URLs or IDs",
            "type": "array",
            "description": "Category listings to harvest products from, as shop.tiktok.com/us/c/<name>/<categoryId> URLs or bare category IDs. Use these to discover products when you do not have product URLs yet.",
            "items": {
              "type": "string"
            }
          },
          "creatorHandles": {
            "title": "Creator handles or profile URLs",
            "type": "array",
            "description": "Creators to scrape, as @handle, handle, or a www.tiktok.com/@handle URL. Returns follower, like, and video counts plus TikTok Shop seller flags. TikTok only serves a creator's video grid and product showcase to signed-in sessions, so use shoppable videos from the product side for creator-product data.",
            "items": {
              "type": "string"
            }
          },
          "videoUrls": {
            "title": "Video URLs or IDs",
            "type": "array",
            "description": "Videos to scrape stats for, as www.tiktok.com/@handle/video/<id> URLs or bare video IDs. Returns plays, likes, comments, shares, saves, and an engagement rate.",
            "items": {
              "type": "string"
            }
          },
          "includeShopProducts": {
            "title": "Scrape each shop's products",
            "type": "boolean",
            "description": "List the products in every shop and category you pass in. Turn it off to get shop profile rows only.",
            "default": true
          },
          "maxProductsPerShop": {
            "title": "Max products per shop or category",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Upper limit of products taken from each storefront or category grid.",
            "default": 50
          },
          "includeProductDetail": {
            "title": "Open each listed product's page",
            "type": "boolean",
            "description": "Visit every listed product's own page to add variants, SKUs, specifications, description, and compliance details. Slower and one extra page load per product; the listing price is carried over so prices stay readable.",
            "default": false
          },
          "includeShoppableVideos": {
            "title": "Include shoppable videos per product",
            "type": "boolean",
            "description": "For each product page, also return the videos TikTok shows as selling that product, with creator, play count, and like count. This is how you get creator-to-product data.",
            "default": true
          },
          "maxVideosPerProduct": {
            "title": "Max shoppable videos per product",
            "minimum": 0,
            "maximum": 200,
            "type": "integer",
            "description": "Upper limit of video rows kept per product. TikTok shows about 10 per product page.",
            "default": 20
          },
          "includeCreatorVideos": {
            "title": "Scrape each creator's videos",
            "type": "boolean",
            "description": "For every creator you pass in, also return their recent videos with full engagement stats. TikTok withholds the video grid from some sessions, in which case the creator row still comes back with profile stats.",
            "default": true
          },
          "maxVideosPerCreator": {
            "title": "Max videos per creator",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Upper limit of videos taken from each creator profile. TikTok loads them about 35 at a time as the grid scrolls.",
            "default": 50
          },
          "includeRecommendedProducts": {
            "title": "Include recommended products",
            "type": "boolean",
            "description": "Also return the products TikTok recommends alongside each product (more from this shop, top reviewed, you may also like). Good for catalog discovery, and it multiplies the row count.",
            "default": false
          },
          "includeSampleReviews": {
            "title": "Include sample reviews",
            "type": "boolean",
            "description": "Attach the reviews TikTok renders on the product page (about three) under sampleReviews, along with the total review count.",
            "default": false
          },
          "maxItems": {
            "title": "Max items",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Hard cap on dataset rows for the whole run, counting products, shops, videos, and creators. The run stops cleanly when it is reached.",
            "default": 1000
          },
          "region": {
            "title": "Region",
            "type": "string",
            "description": "TikTok Shop country, as an ISO-2 code. US is what this Actor is built and tested for; other regions are best effort because TikTok Shop's catalog, prices, and availability are region-gated.",
            "default": "US"
          },
          "includeRawData": {
            "title": "Include raw TikTok payload",
            "type": "boolean",
            "description": "Attach TikTok's unprocessed payload for each row under `raw`. Useful for fields this Actor does not map yet, and it makes the dataset several times larger.",
            "default": false
          },
          "maxConcurrency": {
            "title": "Max concurrent pages",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many browser pages run at once. Raise it for speed on large runs, lower it to 1 if TikTok starts serving verification challenges.",
            "default": 3
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy for the browser. Datacenter with country US is the default and is what the Actor is tested on. RESIDENTIAL costs around 10x more per run and is the fallback for when TikTok starts refusing datacenter IPs.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyCountry": "US"
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}