# TikTok Product Intelligence (`beastmasteral/tiktok-product-intelligence`) Actor

Research TikTok product demand with organic posts, buyer-intent comments, Shop evidence, transparent commercial signals, history, breakouts, monitoring, and Creative Center ads evidence.

- **URL**: https://apify.com/beastmasteral/tiktok-product-intelligence.md
- **Developed by:** [BeastMaster Al](https://apify.com/beastmasteral) (community)
- **Stats:** 2 total users, 1 monthly users, 95.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.25 / product intelligence analysis

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 Product Intelligence

**Spot product momentum early — with evidence, not hype.**

TikTok Product Intelligence turns a product idea into an auditable evidence pack across organic TikTok posts, buyer-intent comments, TikTok Shop commerce, persistent history, breakout detection, optional Creative Center ads, optional supplier sourcing, public supplier due-diligence signals, and optional landed-cost scenarios.

It is a product-intelligence engine, not a black-box “winning product” score and not an automatic buying decision system.

### What should I enter?

Start with the product idea you already want to investigate. You do **not** need to know an exact TikTok product ID or URL.

Good inputs include:

- a specific product or model: `TOZO NC20 Pro`;
- a product category or niche: `electric bike`, `portable blender`, `walking pad`;
- a supported hashtag, creator, TikTok video/profile URL, or TikTok Shop product/seller URL when you already have one.

TikTok Product Intelligence evaluates the idea or scope you give it. It does **not** autonomously scan all of TikTok and choose today's “best products” for you.

### What you get

A run can produce structured records for:

- TikTok organic posts and creators;
- comments classified into buyer intent, price, availability, shipping, product questions, and sentiment;
- TikTok Shop product, seller, price, sold-count, rating, and review evidence;
- conservative product clusters with explicit `REVIEW_REQUIRED` states;
- transparent commercial signals with visible formulas;
- persistent same-scope snapshots;
- change, velocity, and breakout evidence after enough history exists;
- durable monitoring state and optional signed webhook alerts;
- public TikTok Creative Center ad evidence;
- optional supplier offers, MOQ, quantity tiers, and observed wholesale costs;
- public supplier due-diligence signals for human review;
- optional user-declared landed-cost scenarios;
- compact `RUN_SUMMARY.json` output.

### Start small

Use the default Store example for a useful first run without the optional higher-cost sources:

```json
{
  "query": "electric bike",
  "country": "US",
  "maxPosts": 5,
  "maxCommentsPerPost": 3,
  "includeShop": true,
  "shopMarket": "US",
  "maxShopProducts": 5,
  "includeAds": false,
  "includeSuppliers": false,
  "includeLandedCost": false,
  "monitor": false
}
```

Optional ads, supplier sourcing, and monitoring can add upstream cost. Review the first dataset before enabling them. The small default limits also keep Apify Store health checks fast and inexpensive.

### Supplier sourcing

Supplier sourcing is optional and disabled by default.

```json
{
  "query": "electric bike",
  "includeSuppliers": true,
  "maxSupplierOffers": 20,
  "supplierTargetQuantity": 10
}
```

The Actor normalizes public supplier rows such as price ranges, quantity-price tiers, MOQ, supplier profile/trust fields, certifications, and provenance. Automatic links require product-specific evidence. Brand-only, generic, or ambiguous supplier rows remain unresolved.

When retail and supplier evidence already use the same currency, the Actor can calculate:

```text
retail price - observed supplier unit cost
```

That is a **gross spread proxy**, not landed margin or profit.

### Supplier due diligence

For product-linked supplier offers, the Actor can expose observed marketplace/profile signals such as:

- Trade Assurance;
- supplier badges or assessment flags when present;
- years on platform;
- review score/count;
- response rate;
- certifications.

These fields are evidence for human review. They do **not** mean the supplier has been independently verified by TikTok Product Intelligence.

The Actor does not independently verify supplier identity, manufacturing capability, product compliance, sample quality, or transaction safety, and it does not rank suppliers.

### Landed-cost scenario

Landed-cost analysis is optional, disabled by default, and requires supplier sourcing.

Example:

```json
{
  "query": "electric bike",
  "includeSuppliers": true,
  "supplierTargetQuantity": 10,
  "includeLandedCost": true,
  "landedCostCurrency": "USD",
  "sourcingDestinationCountry": "SI",
  "freightPerUnit": 35,
  "customsDutyPerUnit": 18,
  "nonRecoverableImportTaxPerUnit": 0,
  "otherImportCostPerUnit": 7
}
```

The formula is deliberately simple and visible:

```text
landed cost per unit
= observed supplier unit cost
+ freight per unit
+ customs duty per unit
+ non-recoverable import tax per unit
+ other import cost per unit
```

The import-cost amounts are **user-declared inputs**. The Actor does not determine customs classification, duty, VAT/tax treatment, freight quotes, or regulatory obligations. There are no hidden numeric defaults; enter `0` only when you have evidence that an amount is zero.

Supplier cost, retail evidence, and declared amounts must use the same currency. The Actor performs no FX conversion.

When the scenario is computable, the Actor can show:

```text
retail price - landed-cost scenario
```

as a `landedGrossSpreadProxy`.

This remains a scenario, not gross profit, net profit, ROAS, or a forecast. Selling fees, payment fees, fulfillment, returns, ads, compliance, warranty, overhead, and other operating costs are outside the calculation, so profitability can remain `UNKNOWN`.

### Evidence-first rules

The Actor intentionally preserves uncertainty:

- weak Shop matches remain `REVIEW_REQUIRED`;
- generic organic posts/comments are not forced onto products;
- brand-only ads or supplier rows are insufficient for product linkage;
- variant-family cumulative counters are not summed without evidence;
- one snapshot is not a trend;
- cumulative counter decreases fail closed as reset/coverage changes;
- Creative Center does not represent every TikTok ad;
- supplier listings do not prove identical product identity or supplier reliability;
- user-declared landed-cost amounts remain clearly labeled as user inputs.

### Monitoring and breakout detection

Repeated runs with the same canonical scope build persistent history. Once enough comparable observations exist, TikTok Product Intelligence can produce change and breakout evidence instead of treating a single snapshot as a trend.

Monitoring is disabled by default. When enabled, the Actor retains durable breakout-alert state across repeated same-scope runs. For recurring execution, create an Apify Schedule outside the Actor using the same input. The public Actor intentionally does not create or modify account schedules, so it can run with limited permissions. Optional webhook delivery uses environment secrets rather than public input.

### Output

Use `recordType` to filter the default dataset. Important records include:

- `summary`
- `product_cluster`
- `commercial_signal`
- `snapshot`
- `change_signal`
- `monitor_event`
- ads records and reports
- `supplier_offer`
- `supplier_cost_signal`
- `supplier_verification_evidence`
- `landed_cost_scenario`
- `landed_cost_report`
- `performance_report`

The default key-value store also exposes `RUN_SUMMARY.json` for a compact run-level overview.

### What this Actor does not claim

TikTok Product Intelligence does not promise or infer:

- guaranteed winning products;
- guaranteed sales;
- profit or ROAS;
- independently verified suppliers;
- exact total market demand;
- complete visibility into all TikTok advertising;
- customs, tax, or compliance advice.

### Cost controls

The core evidence pipeline has fail-closed request-volume limits. Supplier sourcing has a separate collection budget and is opt-in. Landed-cost calculation itself uses already collected supplier evidence and does not add another upstream collector.

Requested limits are not billing claims. Real cloud cost depends on configured upstream Actors and result counts.

# Changelog

This Actor's version history is a separate document: https://apify.com/beastmasteral/tiktok-product-intelligence/changelog.md

# Actor input Schema

## `query` (type: `string`):

Enter a product name, model, category, or niche. Examples: TOZO NC20 Pro, electric bike, portable blender. You can also use a supported hashtag, @creator, TikTok video/profile URL, or TikTok Shop product/seller URL when you already have one.

## `country` (type: `string`):

Two-letter country code for the organic TikTok research scope, for example US, DE, SI, GB, FR, IT, or ES.

## `maxPosts` (type: `integer`):

Maximum organic TikTok post results requested from the upstream collector.

## `maxCommentsPerPost` (type: `integer`):

Maximum top-level comments requested for each normalized TikTok post. Set to 0 to disable comment collection.

## `includeShop` (type: `boolean`):

Collect TikTok Shop commerce evidence when the query type and market support it.

## `shopMarket` (type: `string`):

AUTO uses country only when the configured Shop source supports it. Otherwise choose a supported cross-market source explicitly.

## `maxShopProducts` (type: `integer`):

Maximum TikTok Shop product rows requested for keyword or seller discovery.

## `includeAds` (type: `boolean`):

Collect public TikTok Creative Center Top Ads evidence and link it conservatively to product clusters when product-specific evidence exists.

## `maxAds` (type: `integer`):

Only used when ads are enabled. Maximum public Creative Center ad rows requested from the upstream collector.

## `adsPeriodDays` (type: `integer`):

Only used when ads are enabled. Creative Center Top Ads lookback window in days.

## `adsSortBy` (type: `string`):

Only used when ads are enabled. Public Creative Center ranking mode passed to the ads source.

## `includeSuppliers` (type: `boolean`):

Search public Alibaba supplier offers after product clustering and link only product-specific matches. Disabled by default to avoid extra upstream cost.

## `maxSupplierOffers` (type: `integer`):

Only used when supplier sourcing is enabled. Maximum Alibaba supplier rows requested from the upstream supplier collector.

## `supplierTargetQuantity` (type: `integer`):

Only used when supplier sourcing is enabled. Quantity used to select a published supplier price tier. Set 0 to use the observed MOQ / first compatible tier.

## `includeLandedCost` (type: `boolean`):

Compute a transparent landed-cost scenario from observed supplier unit cost plus explicit per-unit import-cost inputs. Requires supplier sourcing. Disabled by default.

## `landedCostCurrency` (type: `string`):

Only used when landed-cost scenarios are enabled. Three-letter currency code shared by the supplier unit cost, retail evidence, and all declared landed-cost amounts. No FX conversion is performed.

## `sourcingDestinationCountry` (type: `string`):

Only used when landed-cost scenarios are enabled. Two-letter destination country for the user-declared import-cost scenario. This labels the scenario; TPI does not determine legal customs/tax obligations.

## `freightPerUnit` (type: `number`):

Only used when landed-cost scenarios are enabled. Explicit freight / international shipping amount per unit in the landed-cost currency.

## `customsDutyPerUnit` (type: `number`):

Only used when landed-cost scenarios are enabled. Explicit customs-duty amount per unit. Enter 0 only when you have evidence that the amount is zero.

## `nonRecoverableImportTaxPerUnit` (type: `number`):

Only used when landed-cost scenarios are enabled. Explicit non-recoverable import tax/VAT amount per unit. Do not include recoverable tax as a cost.

## `otherImportCostPerUnit` (type: `number`):

Only used when landed-cost scenarios are enabled. Other explicit import/logistics cost per unit not already included above.

## `monitor` (type: `boolean`):

Keep durable same-scope breakout-alert state across repeated runs. For recurring execution, create an Apify Schedule outside this Actor; the public Actor does not manage account schedules.

## Actor input object example

```json
{
  "query": "TOZO NC20 Pro",
  "country": "US",
  "maxPosts": 5,
  "maxCommentsPerPost": 3,
  "includeShop": true,
  "shopMarket": "US",
  "maxShopProducts": 5,
  "includeAds": false,
  "maxAds": 10,
  "adsPeriodDays": 30,
  "adsSortBy": "for_you",
  "includeSuppliers": false,
  "maxSupplierOffers": 10,
  "supplierTargetQuantity": 10,
  "includeLandedCost": false,
  "landedCostCurrency": "USD",
  "sourcingDestinationCountry": "SI",
  "freightPerUnit": 35,
  "customsDutyPerUnit": 18,
  "otherImportCostPerUnit": 7,
  "monitor": false
}
```

# Actor output Schema

## `results` (type: `string`):

All normalized evidence, product clusters, commercial signals, history/change records, monitoring records, ads evidence, supplier offers/cost proxies, supplier due-diligence evidence, landed-cost scenarios, and performance telemetry.

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

Compact M14 summary with status, counts, warnings, supplier/landed-cost status, and release metadata.

# 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 = {
    "query": "electric bike",
    "maxPosts": 5,
    "maxCommentsPerPost": 3,
    "maxShopProducts": 5,
    "maxAds": 10,
    "maxSupplierOffers": 10,
    "supplierTargetQuantity": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("beastmasteral/tiktok-product-intelligence").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 = {
    "query": "electric bike",
    "maxPosts": 5,
    "maxCommentsPerPost": 3,
    "maxShopProducts": 5,
    "maxAds": 10,
    "maxSupplierOffers": 10,
    "supplierTargetQuantity": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("beastmasteral/tiktok-product-intelligence").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 '{
  "query": "electric bike",
  "maxPosts": 5,
  "maxCommentsPerPost": 3,
  "maxShopProducts": 5,
  "maxAds": 10,
  "maxSupplierOffers": 10,
  "supplierTargetQuantity": 10
}' |
apify call beastmasteral/tiktok-product-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,beastmasteral/tiktok-product-intelligence"
        }
    }
}
```

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/qxXap3aUeS6p2dKlZ/builds/UAmfhP837tf4JzpBj/openapi.json