# TikTok Shop US Scraper — Products, Prices & Stock (`funny_ground/tiktok-shop-us-scraper`) Actor

Extract public TikTok Shop US product prices, SKUs, stock, ratings and sold counters by keyword or product URL. JSON/CSV. $1 per 1,000 snapshots plus Apify platform usage. Keyword first page only.

- **URL**: https://apify.com/funny_ground/tiktok-shop-us-scraper.md
- **Developed by:** [Coor Yu](https://apify.com/funny_ground) (community)
- **Categories:** E-commerce, Social media
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 71.4% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 product snapshots

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## TikTok Shop US Scraper — Products, Prices & Stock

**Public beta — US$1 per 1,000 product snapshots, plus Apify platform usage. No Actor-start fee.**

Read public TikTok Shop US product pages and the first public keyword-results page. Export structured product snapshots for product research, price comparisons and downstream analysis. No login, paid analytics source, automatic paid proxy or browser is used.

### What it does

- Discover products by keyword on the **first public server-rendered results page**, source-dependent and limited to at most 30 candidates per keyword.
- Read direct US product URLs, including supported `www.tiktok.com/shop/pdp/...` links.
- Extract the product ID, title, description, current/original price, currency, SKU prices and stock, images, shop name, public rating/review count, shipping and the public sold counter when available.
- Deduplicate by product ID across all inputs within one run. Direct URLs are processed first.
- Optionally include **up to five embedded review samples**. These are not all reviews and are not guaranteed to be the newest.
- Compare a supplied earlier `SNAPSHOT` against the current snapshot for compatible price, stock and counter changes.
- Produce product-only datasets, JSON, spreadsheet-safe CSV, and separate diagnostics.

### Honest limits

1. **US storefront only.** Other countries, profiles, videos, arbitrary websites, shortened links, categories and shop URLs are not supported inputs in this release.
2. **First keyword page only.** There is no cursor/API pagination. If TikTok reports more results, the run emits `FIRST_PAGE_ONLY` in `NOTICES`. Increasing a limit does not invent more products.
3. **Counter scope is explicit.** A product may display global lifetime items sold, excluding returns. That is not US-only sales, not a 7/30-day metric and not official GMV. Rounded counters are marked. No purchased GMV or revenue split is provided.
4. **Missing means null, not zero.** SKU stock may be incomplete, stale or hidden. A stock sum is returned only if every returned SKU has a usable stock value. Listing-only results do not pretend to contain SKU stock.
5. **No silent paid fallback.** A denied/rate-limited response is reported. No proxy, unblocking service, vendor API or other Actor is purchased automatically. Cloud IPs can behave differently from the local development environment.
6. **No full review scraping.** Embedded samples are optional, stay inside the product row and omit reviewer names, avatars and profile links.
7. **No built-in recurring service.** `previousProducts` is a caller-supplied earlier snapshot. This Actor does not schedule itself or maintain a cross-customer historical database.
8. **Search relevance is not guaranteed by TikTok.** The default title filter requires each case-insensitive Unicode word/number token as a substring. Disable it to accept broader source results.

### Quick start

Keyword discovery with detail pages:

```json
{
  "keywords": ["air fryer"],
  "maxProducts": 10,
  "maxProductsPerKeyword": 10,
  "includeProductDetails": true,
  "strictKeywordMatch": true,
  "maxRequests": 20
}
```

Direct public product URL:

```json
{
  "startUrls": [
    { "url": "https://shop.tiktok.com/us/pdp/cat-nail-clipper-by-potaroma-adjustable-sizes-built-in-file-safe-for-kittens-cats/1731578642912612516" }
  ],
  "maxProducts": 1,
  "includeReviewSamples": false,
  "maxRequests": 3,
  "maxRetries": 0
}
```

The example product is a live public listing, not a guaranteed permanent test fixture. It can change or disappear.

### Main input controls

| Input | Default | Meaning |
|---|---|---|
| `keywords` | `[]` | Up to 20 search phrases, 150 characters each |
| `startUrls` | `[]` | Up to 100 public US product URLs |
| `maxProducts` | `20` | Global maximum unique product results, 1–500 |
| `maxProductsPerKeyword` | `25` | Per-keyword result upper bound, 1–30 |
| `includeProductDetails` | `true` | Open discovered products; additional HTTP work |
| `strictKeywordMatch` | `true` | Require the keyword's tokens in the title |
| `includeReviewSamples` | `false` | Include already-embedded review samples only |
| `minPrice`, `maxPrice` | not set | Current US price filter |
| `minSoldCount`, `minRating` | not set | Public-counter and product-rating filters |
| `previousProducts` | `[]` | Earlier `SNAPSHOT` array for comparison |
| `maxRequests` | `100` | All HTTP attempts, including redirects/retries |
| `maxRunSeconds` | `180` | Application runtime guard, checked between requests |
| `requestTimeoutSecs` | `20` | In-flight request timeout, 3–45 seconds |
| `maxRetries` | `1` | Only transient network/timeouts and selected 5xx statuses |
| `requestDelayMillis` | `250` | Delay between public requests |

The application runtime guard is not a precise invoice cap. An in-flight request can take up to the request timeout beyond it. Also set the Apify run timeout and appropriate memory.

### Output

The default dataset contains **only valid product rows**, never error/notice objects. Important fields:

- `productId` (string; large IDs are never converted into imprecise numbers), `url`, `country`, `title`, `description`.
- `price`, `originalPrice`, `currency`, `discountPercent`, `variants`, `stockQuantity`, `stockIsComplete`, `inStock`.
- `soldCount`, `soldCountRaw`, `soldCountIsApproximate`, `soldCountScope`, `soldCountNote`.
- `rating`, `reviewCount`, `shopId`, `shopName`, `shopRating`, `shipping`, `categories`, `specifications`.
- `dataSource`, `dataLevel`, `sourceType`, `sourceInput`, `position`, `capturedAt`, `missingFields`, `warnings`, `changes`.

Key-value records:

| Record | Contents |
|---|---|
| `OUTPUT` | Full product array |
| `OUTPUT.csv` | UTF-8 BOM CSV; formula-like untrusted text is neutralized |
| `SUMMARY` | Result counts, request counts, source coverage, errors and stop reason |
| `ERRORS` | Invalid inputs, denied/unavailable pages and parsing failures |
| `NOTICES` | First-page-only and no-result notices |
| `SNAPSHOT` | Minimal array suitable as a later run's `previousProducts` |

Zero results due exclusively to source/parsing errors make the cloud run fail after saving diagnostics. A legitimate empty keyword feed or all-filtered results are reported as empty, not silently replaced with recommendations.

### Snapshot comparisons

Copy an earlier run's `SNAPSHOT` array into `previousProducts` of a later run. Price deltas require compatible known currencies. Stock deltas require known quantities. Counter-difference estimates require matching known counter scope, exact counters and a non-decreasing counter. Future timestamps and counter resets do not produce fake sales figures.

Counter differences can still be affected by returns, corrections and source timing. They are not verified net sales, not historical GMV and not a generated 7/30-day series.

### Pricing and spending controls

#### Price: product events **plus platform usage**

- **US$0.001 per unique product snapshot saved to the dataset (US$1 per 1,000), at the same service rate for every plan tier.**
- **Apify compute, storage, traffic and other platform usage are charged separately to the caller. This is not an all-inclusive US$1 bill.** The Store Pricing tab and the run's usage detail show the applicable charges.
- **No Actor-start fee.** There are no separate events for SKU arrays, images, shipping fields or embedded review samples.
- Listing-only and detail snapshots have the same product-event price. Missing optional fields are explicitly null; a result is not a promise that every source field exists.
- Errors, rejected inputs, notices and filtered-out products do not produce a product event. Platform resources used while attempting a request can still be charged, including when no results are returned.

Example: 3 delivered products incur **US$0.003 in product events, plus the actual platform usage**. A user spending limit for events is not a combined cap on the separately billed platform usage; set a platform timeout, memory and the input's HTTP/time limits as well.

The minimum permitted **event budget** is US$0.01. It is not a minimum spend: only delivered product events are charged. The default event budget is US$0.05 and can stop a run before its requested product maximum; increase it explicitly when needed.

The Actor uses the custom `product` event through the SDK's push/charge integration and refuses configurations with both `product` and `apify-default-dataset-item`, preventing duplicate result-event configuration. It checks event affordability before further network work. Diagnostics are kept outside the product dataset.

Dataset reconciliation on a resurrected run reduces duplicate outputs; SDK retries handle event API idempotency. This does not constitute a guarantee of exactly-once behavior across every possible distributed-system crash boundary.

### Local development and verification

Requires Node.js 22 or newer.

```bash
npm ci --ignore-scripts --no-audit --no-fund
npm run check
npm test
npm run smoke:fixtures
```

`smoke:fixtures` reads minimized captured public responses. It makes no external network call and no Apify call. Unit-test mutations/mocks are synthetic and are not presented as live results.

```bash
npm run smoke:live
```

`smoke:live` makes a bounded local public-HTTP check (no SDK initialization and no paid provider). It writes fresh results to `generated/reports/live`. It is not a cloud-run or billing verification.

### Deployment and verification

- Source version: `0.1`; package version: `0.1.0`; release tag: `latest`.
- Memory bounds: 256–512 MB; no Chromium image or automatically purchased proxy.
- The input, dataset, output and Actor definitions pass Apify's official schema validators.
- The parsing, filtering, request-budget and billing-adapter unit tests pass on Node 22.
- A real Apify datacenter run returned three detail products with four public HTTP requests and no errors. This is a small-sample check, not a claim of universal or long-term success.

Check the active Store Pricing page for the current product-event rate and the separate platform-usage model. Do not rely on an old source archive as proof of current pricing.

### Data use and support

Read only publicly accessible pages; do not supply login cookies or credentials. Ensure your use, retention and redistribution comply with applicable law, TikTok's terms and any contractual obligations. Public access is not a blanket license for all downstream uses. Report a problem with the run ID and `ERRORS`/`SUMMARY` records; remove private information before sharing logs.

# Actor input Schema

## `keywords` (type: `array`):

One keyword per line. US storefront only. This release reads only the server-rendered first page, up to 30 source-dependent candidates per keyword. Results are deduplicated across keywords and URLs.

## `startUrls` (type: `array`):

Direct https://shop.tiktok.com/us/pdp/... or https://www.tiktok.com/shop/pdp/... product links. Only public US product pages; not profiles, videos, short links, categories or other countries.

## `maxProducts` (type: `integer`):

A global limit shared by direct URLs and all keywords. Direct URLs are processed first. Fewer products may be available.

## `maxProductsPerKeyword` (type: `integer`):

Upper bound per keyword, still subject to the whole-run limit and the first public page's available products. No hidden recommendation fallback.

## `includeProductDetails` (type: `boolean`):

Open each discovered product for SKUs, stock, shipping and description. Adds HTTP requests. If a detail request fails, it is reported and skipped, not silently sold as a complete result. Direct product URLs always open product pages.

## `strictKeywordMatch` (type: `boolean`):

Case-insensitive substring matching of each Unicode word/number token. Disable to accept the source search's broader results.

## `includeReviewSamples` (type: `boolean`):

At most five already-embedded public reviews, included in the product row. Not all reviews, not guaranteed newest, no review pagination. Reviewer names, avatars and profiles are omitted. Requires a detail page.

## `minPrice` (type: `number`):

Keep products at or above this current USD price. Missing prices do not pass.

## `maxPrice` (type: `number`):

Keep products at or below this current USD price. Missing prices do not pass.

## `minSoldCount` (type: `number`):

The source may show global lifetime items sold, not US-only or 7/30-day sales. Rounded counters are explicitly marked in output.

## `minRating` (type: `number`):

Keep products at or above this product rating, from zero to five. Missing ratings do not pass.

## `previousProducts` (type: `array`):

Paste the array from an earlier SNAPSHOT record. Compare only the same product, valid earlier timestamps and compatible units/currencies. This does not schedule runs or maintain a shared tracking database.

## `maxRequests` (type: `integer`):

Includes search pages, product pages, redirects and explicit retries. No request after this bound.

## `maxRunSeconds` (type: `integer`):

Stop starting new work after this application time limit; also set the Apify platform timeout.

## `requestTimeoutSecs` (type: `integer`):

Maximum wait for one HTTP request; redirects count as separate requests.

## `maxRetries` (type: `integer`):

Only transient network/timeouts and selected 5xx responses. No repeated retries for 401/403/429, missing products or invalid pages.

## `requestDelayMillis` (type: `integer`):

Wait this many milliseconds between public HTTP attempts.

## Actor input object example

```json
{
  "keywords": [
    "air fryer"
  ],
  "startUrls": [],
  "maxProducts": 20,
  "maxProductsPerKeyword": 25,
  "includeProductDetails": true,
  "strictKeywordMatch": true,
  "includeReviewSamples": false,
  "previousProducts": [],
  "maxRequests": 100,
  "maxRunSeconds": 180,
  "requestTimeoutSecs": 20,
  "maxRetries": 1,
  "requestDelayMillis": 250
}
```

# Actor output Schema

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

No description

## `csv` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `snapshot` (type: `string`):

No description

## `errors` (type: `string`):

No description

## `notices` (type: `string`):

No description

# 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 = {
    "keywords": [
        "air fryer"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("funny_ground/tiktok-shop-us-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 = { "keywords": ["air fryer"] }

# Run the Actor and wait for it to finish
run = client.actor("funny_ground/tiktok-shop-us-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 '{
  "keywords": [
    "air fryer"
  ]
}' |
apify call funny_ground/tiktok-shop-us-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,funny_ground/tiktok-shop-us-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/UiA5fdElgkfe9qtMr/builds/hS2S5FCeZef5pc7y4/openapi.json
