# TikTok Shop USA Scraper: Products, Shops, Creators (`capable_cauldron/tiktok-shop-usa-scraper`) Actor

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.

- **URL**: https://apify.com/capable_cauldron/tiktok-shop-usa-scraper.md
- **Developed by:** [Capable Cauldron](https://apify.com/capable_cauldron) (community)
- **Categories:** E-commerce, Social media
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 product scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

This **TikTok Shop scraper** collects **TikTok Shop USA** data by URL, ID, or handle: **product detail** with price, discount, units sold, rating, variants and SKUs, **shop profiles** with follower and lifetime sales counts, **shoppable video stats** showing which creators sell a product and how those videos performed, and **creator profiles** with TikTok Shop seller flags. Everything lands in one dataset with a `type` column, so products, shops, videos and creators come back from a single run. **No login, cookies, or API keys.**

Point it at a product, a storefront, a category, a creator, or a video and it expands from there: a shop URL returns its whole catalog, a product URL returns the videos selling it. Built on Apify, so you can **schedule** a daily price and sales sweep, call it from the **API** or a webhook, and push results to **Google Sheets**, Airtable, or your warehouse. Click **Try for free** to open it in Console. Apify's free plan includes $5 of monthly credit, which buys roughly **2,000 products** or **5,000 video stat rows**.

See a real run in 47 seconds:

[![TikTok Shop USA Scraper demo video, 47 seconds](https://api.apify.com/v2/key-value-stores/9FGooi7IrKs0P8DcV/records/tiktok-shop-usa-scraper-demo-poster.jpg)](https://api.apify.com/v2/key-value-stores/9FGooi7IrKs0P8DcV/records/tiktok-shop-usa-scraper-demo.mp4)

▶️ [Watch the 47-second demo](https://api.apify.com/v2/key-value-stores/9FGooi7IrKs0P8DcV/records/tiktok-shop-usa-scraper-demo.mp4) (MP4, 20 MB, opens in your browser) · [Transcript](https://api.apify.com/v2/key-value-stores/9FGooi7IrKs0P8DcV/records/tiktok-shop-usa-scraper-demo-transcript.srt)

### What data can you extract from TikTok Shop?

- 🛒 **Product detail**: title, price, original price, discount, currency, units sold, rating, review count
- ⭐ **Rating breakdown**: how many 1, 2, 3, 4 and 5 star reviews sit behind that average
- 🎛️ **Variants and SKUs**: option names and values, per-SKU price, stock, weight, dimensions, pre-order flags
- 🚚 **Shipping and stock**: shipping fee, free-shipping promotions, delivery estimate, units available
- 📋 **Specs and description**: the full specification table, brand, and the description as plain text
- 🏪 **Shop profiles**: shop rating, lifetime units sold, review count, followers, video count, catalog size, badge
- 🔎 **Seller stats on every product row**: the shop's rating, followers and catalog size, with no second request
- 🔤 **TikTok's own SEO copy**: the title, description and keywords TikTok generates for the product
- 🎬 **Shoppable video stats**: plays, likes, comments, shares, saves, reposts, and an engagement rate
- 🤝 **Creator to product links**: for each product, the creators whose videos sell it, with commission labels
- 👤 **Creator profiles**: followers, total likes, video count, commerce account and TikTok Shop seller flags
- 🗂️ **Category harvesting**: walk a category grid to discover products when you have no URLs yet
- 📇 **Compliance**: registered business name and address, as TikTok publishes them
- ⭐ **Sample reviews**: the reviews TikTok renders on the page, with rating, date, and verified-purchase flag
- 📤 Export to **CSV, Excel, JSON, or XML**, or pull results through the API

#### What each input type returns

| You give it | You get back | Price readable |
|---|---|---|
| Product URL or ID | 1 product row with full detail, plus a video row per creator selling it | Only when TikTok shows it publicly |
| Shop URL or seller ID | 1 shop row plus a product row per item in the catalog | Yes |
| Category URL or ID | A product row per item in the grid | Yes |
| Creator handle or profile URL | 1 creator row plus a video row per recent video | n/a |
| Video URL or ID | 1 video row with every engagement counter | n/a |

#### Why some prices come back hidden

Some product pages hide price digits from visitors who are not signed in, showing `$4*` next to an "Unlock price" button; other pages show the full price. This Actor never guesses hidden digits. It sets `priceMasked: true` when needed and keeps the discount percentage. Shop and category listings can also provide a readable price, which `includeProductDetail` carries onto the detail row.

### How to scrape TikTok Shop products, shops, and creator videos

1. Click **Try for free** to open the Actor in Apify Console.
2. Paste what you have. Product URLs go in `productUrls`, storefronts in `shopUrls`, category pages in `categoryUrls`, creators in `creatorHandles`, videos in `videoUrls`. Bare IDs work in every field.
3. Leave the proxy on **Apify Proxy** with country **US**. TikTok Shop is region-gated, so a US exit IP is what makes the data US data.
4. Set `maxItems` to cap the run. 100 is plenty for a first look.
5. Click **Start**, watch the log, then open the **Products**, **Shops**, **Shoppable videos**, or **Creators** tab of the dataset.
6. Export as CSV or Excel, or copy the API endpoint for the view you want.

#### Getting a product, shop, or creator ID

Every TikTok Shop URL ends in the ID, so you rarely need to look one up. In `https://shop.tiktok.com/us/pdp/zero-sugar-best-seller-trio-goli-ashwagandha-gummies-vegan-non-gmo/1731194857673101831` the product ID is the trailing number, and in `https://shop.tiktok.com/us/store/goli-nutrition/7495794203056835079` the seller ID is. Paste either the whole URL or just the number.

### How much does it cost to scrape TikTok Shop?

Pricing is per event, so you pay for rows you actually get. Compute time is not charged on top.

| Event | When it fires | Price |
|---|---|---|
| `product-scraped` | Each product row, listing or full detail | $0.002 |
| `video-scraped` | Each video row with its engagement stats | $0.001 |
| `shop-scraped` | Each shop profile row | $0.01 |
| `creator-scraped` | Each creator profile row | $0.005 |
| Actor start | Per GB of allocated memory when the run starts | $0.005 per GB ($0.02 at the 4 GB default) |

**Worked examples**

- One storefront with 50 products: 50 products + 1 shop, costs **$0.13**
- 10 competitor storefronts, 100 products each: 1,000 products + 10 shops, costs **$2.12**
- 200 product URLs with their shoppable videos (about 10 videos each): 200 products + 2,000 videos, costs **$2.42**
- One creator profile with 50 videos: 1 creator + 50 videos, costs **$0.08**

Apify's free plan ($5 per month) covers about 2,000 products, or 5,000 video rows, with no card required. Those estimates assume a single run at the default 4 GB memory; each additional run has its own start charge. To cap spend, set `maxItems`, lower `maxProductsPerShop` and `maxVideosPerProduct`, or turn off `includeShoppableVideos`. The run also stops itself the moment your Apify spending limit is reached.

### Input

Every field is optional on its own, but the run needs at least one target. Mix as many as you like in one run.

| Field | Type | Default | What it does |
|---|---|---|---|
| `productUrls` | array | `[]` | Product pages to scrape, as any TikTok Shop product URL or a bare product ID |
| `shopUrls` | array | `[]` | Storefronts to scrape, as store URLs or bare seller IDs. Returns the shop plus its catalog |
| `categoryUrls` | array | `[]` | Category listings to harvest products from, as category URLs or bare category IDs |
| `creatorHandles` | array | `[]` | Creators to scrape, as `@handle`, `handle`, or a profile URL |
| `videoUrls` | array | `[]` | Videos to get stats for, as video URLs or bare video IDs |
| `includeShopProducts` | boolean | `true` | List the products in each shop and category. Off gives shop profile rows only |
| `maxProductsPerShop` | integer | `50` | Cap on products taken from each storefront or category grid |
| `includeProductDetail` | boolean | `false` | Open every listed product's own page for variants, SKUs, specs, and description |
| `includeShoppableVideos` | boolean | `true` | For each product, return the videos selling it with creator and play counts |
| `maxVideosPerProduct` | integer | `20` | Cap on video rows per product. TikTok shows about 10 per product page |
| `includeCreatorVideos` | boolean | `true` | For each creator, return their recent videos with full engagement stats |
| `maxVideosPerCreator` | integer | `50` | Cap on videos taken from each creator profile |
| `includeRecommendedProducts` | boolean | `false` | Also return the products TikTok recommends beside each product |
| `includeSampleReviews` | boolean | `false` | Attach the reviews rendered on the product page under `sampleReviews` |
| `maxItems` | integer | `1000` | Hard cap on dataset rows for the whole run, across all four types |
| `region` | string | `US` | TikTok Shop country as an ISO-2 code. US is what this Actor is built and tested for |
| `includeRawData` | boolean | `false` | Attach TikTok's unprocessed payload under `raw` |
| `maxConcurrency` | integer | `3` | Browser pages at once. Lower it to 1 if TikTok starts challenging the run |
| `proxyConfiguration` | object | Apify Proxy, US | Proxy for the browser. Datacenter is the default and is what the Actor is tested on. Keep the country on US |

```json
{
  "shopUrls": ["https://shop.tiktok.com/us/store/goli-nutrition/7495794203056835079"],
  "productUrls": ["1731194857673101831"],
  "creatorHandles": ["@golinutrition"],
  "maxProductsPerShop": 20,
  "maxVideosPerProduct": 10,
  "includeSampleReviews": true,
  "maxItems": 100,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "US"
  }
}
```

### Output

These are representative rows from product, shop, creator, and video runs. Values change as TikTok Shop changes. A product row carries 52 fields, a video row 45, a creator row 25, a shop row 17. Fields a row type does not have are simply absent, and `type` tells them apart.

```json
{
  "type": "product",
  "productId": "1731194857673101831",
  "title": "Goli Zero Sugar Best Seller Trio - Daily Gut & Wellness Support",
  "url": "https://shop.tiktok.com/us/pdp/zero-sugar-best-seller-trio-goli-ashwagandha-gummies-vegan-non-gmo/1731194857673101831",
  "detailLevel": "detail",
  "shopId": "7495794203056835079",
  "shopName": "Goli Nutrition",
  "priceCurrent": 49.37,
  "priceOriginal": 74.1,
  "currency": "USD",
  "discountPercent": 33,
  "priceMasked": false,
  "priceSource": "detail",
  "soldCount": 1036865,
  "rating": 4.4,
  "reviewCount": 48836,
  "freeShipping": true,
  "shippingFee": 0,
  "shippingOption": "Standard shipping",
  "inStock": true,
  "totalStock": 190039,
  "shopRating": 4.6,
  "shopFollowerCount": 601228,
  "shopProductCount": 52,
  "seoTitle": "Zero Sugar Best Seller Trio Gummies",
  "categoryNames": ["Health", "Nutrition & Wellness", "Vitamins, Minerals & Wellness Supplements"],
  "variants": [{ "name": "Combined Variations", "values": ["1x zs asw 1x zs ppp 1x zs acv"] }],
  "skus": [{ "skuId": "1731194889857176071", "availableQuantity": 190039, "inStock": true, "priceCurrent": 49.37 }],
  "specifications": { "Brand": "Goli", "Manufacturer": "goli nutrition" },
  "businessName": "Goli Nutrition Inc.",
  "deliveryMinDays": 5,
  "deliveryMaxDays": 8
}
```

This product page showed its full price. When a page masks digits, `priceCurrent` is null and `priceMasked` is true; a shop listing may still show a readable price.

```json
{
  "type": "product",
  "productId": "1729587769570529799",
  "title": "3 Bottles of Goli Ashwagandha & Vitamin D Gummy - Mixed Berry, KSM-66",
  "detailLevel": "listing",
  "shopId": "7495794203056835079",
  "shopName": "Goli Nutrition",
  "priceCurrent": 58.47,
  "priceOriginal": 74.1,
  "currency": "USD",
  "discountPercent": 21,
  "priceMasked": false,
  "priceSource": "listing",
  "soldCount": 864311,
  "rating": 4.7,
  "reviewCount": 71740,
  "promotionLabels": ["Free shipping"],
  "url": "https://shop.tiktok.com/us/pdp/goli-ashwagandha-gummies/1729587769570529799"
}
```

```json
{
  "type": "video",
  "videoId": "7419446014324624686",
  "url": "https://www.tiktok.com/@i/video/7419446014324624686",
  "creatorId": "6596631738335674373",
  "creatorNickname": "Gonzalo",
  "playCount": 8417460,
  "likeCount": 505880,
  "commentCount": 1642,
  "shareCount": 6815,
  "saveCount": 35783,
  "engagementRate": 0.0601,
  "isShoppable": true,
  "commissionLabel": "Creator earns commission",
  "productId": "1729587769570529799",
  "productTitle": "3 Bottles of Goli Ashwagandha & Vitamin D Gummy",
  "shopName": "Goli Nutrition",
  "createdAt": "2024-09-27T21:59:55+00:00"
}
```

```json
{
  "type": "shop",
  "shopId": "7495794203056835079",
  "shopName": "Goli Nutrition",
  "rating": 4.6,
  "soldCount": 5734372,
  "reviewCount": 407412,
  "followerCount": 598490,
  "videoCount": 4720,
  "productCount": 52,
  "productsScraped": 20
}
```

```json
{
  "type": "creator",
  "creatorHandle": "golinutrition",
  "creatorNickname": "Goli® Nutrition",
  "followerCount": 598500,
  "likeCount": 4200000,
  "videoCount": 192,
  "isCommerceUser": true,
  "isTikTokSeller": true,
  "commerceCategory": "Shopping & Retail",
  "videosScraped": 50
}
```

The dataset ships four ready-made views (**Products**, **Shops**, **Shoppable videos**, **Creators**) so you can export one entity type without filtering by hand. The run also writes an `OUTPUT` record to the key-value store with row counts per type, pages crawled, error counts by category, and notes such as how many prices TikTok hid.

### Use cases

- [Scrape a TikTok Shop storefront catalog](https://apify.com/capable_cauldron/tiktok-shop-usa-scraper/examples/ttshop-scrape-a-tiktok-shop-storefront-catalog). Pull a seller's whole TikTok Shop catalog with price, discount, units sold and rating on every product, plus the shop's rating and follower count.
- [Find the creators selling a TikTok Shop product](https://apify.com/capable_cauldron/tiktok-shop-usa-scraper/examples/ttshop-find-creators-selling-a-tiktok-shop-product). For any product, get the creators whose videos sell it, with plays, likes, saves and an engagement rate, so you can rank affiliates on performance.
- [Find best selling products in a TikTok Shop category](https://apify.com/capable_cauldron/tiktok-shop-usa-scraper/examples/ttshop-find-best-selling-products-in-a-category). Harvest a TikTok Shop category grid and sort by units sold and rating to see what is actually selling before you source or launch a product.
- [Track TikTok Shop competitor prices and stock](https://apify.com/capable_cauldron/tiktok-shop-usa-scraper/examples/ttshop-track-competitor-prices-and-stock-daily). Watch rival storefronts on a schedule. Every run records price, discount, per SKU stock and units sold, so price history builds itself over time.
- [Get engagement stats for TikTok videos](https://apify.com/capable_cauldron/tiktok-shop-usa-scraper/examples/ttshop-get-engagement-stats-for-tiktok-videos). Paste video URLs or IDs and get plays, likes, comments, shares, saves and an engagement rate for each one, plus the creator behind it.
- [Audit a TikTok Shop seller and its creators](https://apify.com/capable_cauldron/tiktok-shop-usa-scraper/examples/ttshop-audit-a-tiktok-shop-seller-and-its-creators). The flagship run: one shop, its catalog, the videos selling each product and the seller's own creator profile, all in a single dataset.

### API and integrations

Run it from any language with the Apify API, or from the CLI. The Actor ID is `capable_cauldron/tiktok-shop-usa-scraper`.

JavaScript:

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('capable_cauldron/tiktok-shop-usa-scraper').call({
    shopUrls: ['7495794203056835079'],
    maxProductsPerShop: 50,
    proxyConfiguration: { useApifyProxy: true, apifyProxyCountry: 'US' },
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const products = items.filter((item) => item.type === 'product');
console.log(products.length, 'products');
```

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("capable_cauldron/tiktok-shop-usa-scraper").call(run_input={
    "productUrls": ["1731194857673101831"],
    "includeShoppableVideos": True,
    "maxVideosPerProduct": 20,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyCountry": "US",
    },
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    if item["type"] == "video":
        print(item["creatorHandle"], item["playCount"], item["engagementRate"])
```

CLI:

```bash
apify call capable_cauldron/tiktok-shop-usa-scraper --input='{"categoryUrls":["700645"],"maxProductsPerShop":100}'
```

Schedules, webhooks, and the Apify integrations for Google Sheets, Airtable, Slack, Zapier, and Make all work with this Actor. A common setup is a nightly schedule over your competitor list with a webhook that appends new rows to a sheet, so price history builds itself.

### FAQ

#### Is scraping TikTok Shop legal?

Scraping publicly available data is generally legal. This Actor only reads pages any visitor can open without signing in, and it collects product, shop, and video information rather than personal data. Creator rows hold the public profile stats TikTok shows on the profile page. You are responsible for how you use what you collect, including compliance with GDPR, CCPA, and TikTok's terms where they apply to you. If you plan to collect personal data, take legal advice first.

#### Why is `priceCurrent` empty and `priceMasked` true?

TikTok masks prices on some product pages from visitors who are not signed in. Guessing the missing digits would put wrong prices in your dataset, so the Actor flags the row instead. Shop and category listings can show the full price; scrape by `shopUrls` or `categoryUrls`, or set `includeProductDetail` to `true` to carry the listing price onto the detail row.

#### Do I need a residential proxy?

No. The default is Apify Proxy on its datacenter group with country `US`, and that is what this Actor is tested on. Measured on the same input and the same build, datacenter and residential returned identical rows: same prices, same currency, same region, same shop rating. Residential moved 19 MB of billed traffic per run against datacenter's none, for no extra data. Keep the country on `US`, because TikTok Shop serves a different catalog per region. Switch to the RESIDENTIAL group only if a run starts hitting verification challenges, which is what the `blocked_errors` count in the run summary tells you.

#### Can I get a creator's full product showcase?

Partly. TikTok's web profile has no public showcase page, and it serves the video grid only to some sessions, so a creator row always carries profile stats and carries videos when TikTok provides them (`videosScraped` tells you which happened). The reliable route to creator-to-product data runs the other way: scrape products or a shop with `includeShoppableVideos` on, and every product returns the creators selling it, their videos, and the play counts.

#### How many products can I get from one shop?

As many as the storefront lists, capped by `maxProductsPerShop`. The Actor pages the catalog grid until it runs out or hits your cap. Shops publish their live product count in the `productCount` field, so you can see what you are missing.

#### Does it work for TikTok Shop outside the US?

The `region` field takes any ISO-2 code and the URL shapes are region-aware, so `GB` or `ID` will usually work, but US is the region this Actor is built, tested, and named for. Availability, currency, and which fields TikTok fills in vary by country.

#### Can I scrape TikTok Shop with Python?

Yes. Use the Python snippet above, or export the dataset as CSV and read it with pandas.

#### What happens when TikTok blocks a page?

The Actor detects a challenge, a fallback shell, or a region redirect, then retries that page from a fresh IP. Pages that stay blocked are counted in the `OUTPUT` record by category, so a run that returns fewer rows than expected tells you why. One blocked page never stops the rest of the run.

### Other Actors by capable_cauldron

| Actor | What it does |
|---|---|
| [App Store Reviews Scraper](https://apify.com/capable_cauldron/app-store-reviews-scraper) | Reviews and ratings for iPhone and iPad apps, grouped by app and country |
| [Company Job Postings Scraper](https://apify.com/capable_cauldron/ats-jobs-scraper) | Open roles and hiring summaries from supported company job boards |
| [Bulk Email Validator](https://apify.com/capable_cauldron/email-validator) | Syntax, mail-routing, disposable-domain and role-inbox checks |
| [Verified Work Email Finder](https://apify.com/capable_cauldron/verified-work-email-finder) | Verified professional emails from LinkedIn URLs or a name and company domain |
| [GTM Account Enrichment](https://apify.com/capable_cauldron/gtm-account-enrichment) | Public company contacts, technologies and hiring signals with an account fit score |
| [Investor Database Search](https://apify.com/capable_cauldron/investor-database-search) | Filter investors by stage, industry and geography and export available partner contacts |
| [LinkedIn Comment Scraper](https://apify.com/capable_cauldron/linkedin-comment-scraper) | LinkedIn comments and replies using your own session cookies |
| [LinkedIn Post Comments Scraper](https://apify.com/capable_cauldron/linkedin-post-comments-scraper) | Comments, replies and reactions on public LinkedIn posts without cookies |
| [LinkedIn Profile Posts & Comments Scraper](https://apify.com/capable_cauldron/linkedin-profile-posts-comments-scraper) | Posts from any LinkedIn profile with up to 50 comments and replies per post, no cookies needed |
| [LinkedIn Profile Posts Scraper](https://apify.com/capable_cauldron/linkedin-profile-posts-scraper) | Public profile posts with 56 enriched fields, including engagement and content metadata |
| [Ad Scraper: Meta, Google, LinkedIn & TikTok](https://apify.com/capable_cauldron/multi-channel-ad-intelligence) | Competitor ads from Meta, Google, LinkedIn and TikTok in one dataset |
| [Website Contact Scraper](https://apify.com/capable_cauldron/website-contact-scraper) | Public emails, phone numbers and social profile links from company websites |
| [Website Tech Stack Detector](https://apify.com/capable_cauldron/website-tech-stack-detector) | Visible website technologies and the evidence supporting each detection |
| [LinkedIn Post Search Scraper](https://apify.com/capable_cauldron/linkedin-post-search-scraper) | Keyword searches for public LinkedIn posts with text, authors and engagement |

### Support

Found a bug or a field TikTok changed? Open an issue on the Actor's **Issues** tab with the input you used and the run ID. Issues get a reply within one business day, and a broken parser is usually fixed the same week, because TikTok changes its payloads without notice.

Need a field this Actor does not return yet, a different region, or a custom pipeline into your warehouse? Custom work is available. Ask on the Issues tab and describe what you need.

# Actor input Schema

## `productUrls` (type: `array`):

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.

## `shopUrls` (type: `array`):

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.

## `categoryUrls` (type: `array`):

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.

## `creatorHandles` (type: `array`):

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.

## `videoUrls` (type: `array`):

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.

## `includeShopProducts` (type: `boolean`):

List the products in every shop and category you pass in. Turn it off to get shop profile rows only.

## `maxProductsPerShop` (type: `integer`):

Upper limit of products taken from each storefront or category grid.

## `includeProductDetail` (type: `boolean`):

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.

## `includeShoppableVideos` (type: `boolean`):

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.

## `maxVideosPerProduct` (type: `integer`):

Upper limit of video rows kept per product. TikTok shows about 10 per product page.

## `includeCreatorVideos` (type: `boolean`):

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.

## `maxVideosPerCreator` (type: `integer`):

Upper limit of videos taken from each creator profile. TikTok loads them about 35 at a time as the grid scrolls.

## `includeRecommendedProducts` (type: `boolean`):

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.

## `includeSampleReviews` (type: `boolean`):

Attach the reviews TikTok renders on the product page (about three) under sampleReviews, along with the total review count.

## `maxItems` (type: `integer`):

Hard cap on dataset rows for the whole run, counting products, shops, videos, and creators. The run stops cleanly when it is reached.

## `region` (type: `string`):

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.

## `includeRawData` (type: `boolean`):

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.

## `maxConcurrency` (type: `integer`):

How many browser pages run at once. Raise it for speed on large runs, lower it to 1 if TikTok starts serving verification challenges.

## `proxyConfiguration` (type: `object`):

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.

## Actor input object example

```json
{
  "productUrls": [
    "https://shop.tiktok.com/us/pdp/zero-sugar-best-seller-trio-goli-ashwagandha-gummies-vegan-non-gmo/1731194857673101831"
  ],
  "shopUrls": [],
  "categoryUrls": [],
  "creatorHandles": [],
  "videoUrls": [],
  "includeShopProducts": true,
  "maxProductsPerShop": 50,
  "includeProductDetail": false,
  "includeShoppableVideos": true,
  "maxVideosPerProduct": 20,
  "includeCreatorVideos": true,
  "maxVideosPerCreator": 50,
  "includeRecommendedProducts": false,
  "includeSampleReviews": false,
  "maxItems": 1000,
  "region": "US",
  "includeRawData": false,
  "maxConcurrency": 3,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `products` (type: `string`):

Product rows: price, discount, units sold, rating, review count, variants, SKUs, specifications, description, and shop.

## `shops` (type: `string`):

Storefront rows: shop rating, lifetime units sold, followers, video count, and catalog size.

## `videos` (type: `string`):

Video rows: plays, likes, comments, shares, saves, engagement rate, the creator, and the product sold.

## `creators` (type: `string`):

Creator rows: followers, likes, video count, and TikTok Shop seller flags.

## `runSummary` (type: `string`):

Row counts per entity type, page count, categorized error counts, and any notes such as prices TikTok hid from signed-out visitors.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "productUrls": [
        "https://shop.tiktok.com/us/pdp/zero-sugar-best-seller-trio-goli-ashwagandha-gummies-vegan-non-gmo/1731194857673101831"
    ],
    "shopUrls": [],
    "categoryUrls": [],
    "creatorHandles": [],
    "videoUrls": [],
    "region": "US",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("capable_cauldron/tiktok-shop-usa-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "productUrls": ["https://shop.tiktok.com/us/pdp/zero-sugar-best-seller-trio-goli-ashwagandha-gummies-vegan-non-gmo/1731194857673101831"],
    "shopUrls": [],
    "categoryUrls": [],
    "creatorHandles": [],
    "videoUrls": [],
    "region": "US",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("capable_cauldron/tiktok-shop-usa-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "productUrls": [
    "https://shop.tiktok.com/us/pdp/zero-sugar-best-seller-trio-goli-ashwagandha-gummies-vegan-non-gmo/1731194857673101831"
  ],
  "shopUrls": [],
  "categoryUrls": [],
  "creatorHandles": [],
  "videoUrls": [],
  "region": "US",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyCountry": "US"
  }
}' |
apify call capable_cauldron/tiktok-shop-usa-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,capable_cauldron/tiktok-shop-usa-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bfajn2doeeBs6tYw4/builds/zrt80zvfBFK2EIuzO/openapi.json
