# TikTok Semantic Search & Audit (`heiman/tiktok-semantic-search-audit`) Actor

Find TikTok videos that match your topic with AI-powered relevance analysis, explanations and verified text excerpts. Collect live candidates, reuse datasets, or audit campaign URLs. Export JSON, CSV and a visual report.

- **URL**: https://apify.com/heiman/tiktok-semantic-search-audit.md
- **Developed by:** [Randolfo Carvalho Irades](https://apify.com/heiman) (community)
- **Categories:** Social media
- **Stats:** 1 total users, 0 monthly users, 80.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 analyzed videos

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

## TikTok Semantic Search & Audit

Find TikTok videos that match a topic, understand why they match, and export the evidence. SignalProof combines live candidate collection with AI-powered relevance analysis and a visual report.

Use it for creator research, content discovery, campaign checks and finding posts about a specific consumer problem.

### Start a search

Enter your topic and click **Start**. The default collects up to 30 real candidates and returns up to 20 matches. AI creates up to three short search phrases in the language of your topic; supply `searchQueries` to control these yourself.

```json
{
  "query": "skincare routine for oily acne-prone skin",
  "maxCandidates": 30,
  "maxResults": 20,
  "minRelevance": 0.65,
  "upstreamMaxCostUsd": 1
}
```

### What you receive

- Videos ranked by relevance, with direct TikTok links.
- An explanation in the language of the topic and topic labels.
- An evidence excerpt checked against the original text.
- Creator, caption, publication date and available engagement metrics.
- JSON data, CSV and an HTML report in Portuguese.
- Source dataset and collection run identifiers.

Analysis uses captions, hashtags and transcript text supplied by the source, up to 12,000 characters per video. It does not inspect video frames, transcribe audio or analyze comments. Missing metrics stay `null`.

### Sources and costs

| Source | Input | Collection cost |
| --- | --- | --- |
| `live` (default) | Topic or campaign URLs | Separate [Clockworks TikTok Scraper](https://apify.com/clockworks/tiktok-scraper) run on your account |
| `dataset` | Select an existing `datasetId` | No new collection |
| `inline` | Supply a `videos` array | No new collection |

**Live collection is billed separately from SignalProof.** `upstreamMaxCostUsd` caps the child scraper's event charges. SignalProof's run charge limit applies to this Actor. Source usage/storage may add costs according to its pricing. Discarded candidates can still incur collection charges.

AI analysis is ready to use with the hosted Actor's default configuration; no API key is required. Advanced users can supply their own key through the optional encrypted API key field. External AI usage on a supplied key is paid by its holder. Keys are never included in results. Select `rankingEngine: "semantic"` for local multilingual AI without an external key.

### Import a dataset

Set `source: "dataset"`, select `datasetId` in the form, and describe the topic. The picker grants read access under limited permissions. Standard nested Clockworks records and flattened exports are supported. Keep TikTok IDs as strings to preserve precision.

### Audit campaign URLs

Set `mode: "audit"`, add canonical URLs to `videoUrls`, and optionally describe the campaign topic. Omit `query` for a coverage-only audit. Short links and profile URLs are rejected.

Audit preserves every requested URL, including posts that fail filters. `unavailable_in_source` means the loaded source returned no usable record for the ID; it does not establish deletion. Set `maxCandidates` high enough to cover the requested URLs, especially when reading a dataset.

### Relevance and filters

AI relevance scores range from 0–1: around 0.3 for a passing keyword mention, 0.5 for a partial match, and 0.7 or above for direct relevance. Default threshold: 0.65. Scores are AI assessments, not probabilities. Read the explanation and evidence when making a decision.

`semantic` uses a pinned multilingual MiniLM model cached in the Docker image. It compares the first 400 query characters with four excerpts totaling up to 1,600 text characters, subject to tokenizer limits. `lexical` measures exact normalized word overlap. Errors never silently switch methods.

Filters support required/excluded terms, source-supplied language, minimum views and inclusive UTC publication dates. Unknown fields fail the corresponding active filter. Duplicate IDs keep the first usable record and combine source query labels.

Failed or interrupted collection is labeled partial. Source runs, records and completed AI batches are checkpointed. Restarts reuse them and skip delivered IDs. This reduces repeat work; it is not an exactly-once billing guarantee across abrupt platform failures.

### Output

The default dataset contains selected search results or requested audit rows. Fields include `relevanceScore`, `relevanceReason`, `topics`, `evidence.excerpt`, `evidence.evidenceVerified`, metrics, filter outcomes and source provenance.

Open **Visual report**, **Download CSV** or **Coverage report (JSON)** in the run output. The CSV includes explanations and protects spreadsheet formula prefixes. The JSON report records analyzed/selected/delivered counts, source status and AI token usage.

### Analysis pricing

**US$0.01 per unique collected video analyzed and delivered** (US$10 per 1,000 videos). Missing audit URLs, invalid records, duplicates and rejected search candidates have no analysis charge. Collected audit rows are billable even when they fail filters.

There is no startup fee. Platform usage for SignalProof is included in the analysis price. Live collection charges remain separate. Set a maximum cost per run to limit the number of paid results delivered, and use the collection cost field to control the separate scraper run. Check the Pricing tab for the current price.

# Actor input Schema

## `mode` (type: `string`):

Search ranks and filters candidates. Audit checks every supplied canonical video URL and preserves collected records even when they fail filters.

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

Describe the topic in your language. Required for search; optional for a coverage-only URL audit.

## `source` (type: `string`):

Live collects TikTok candidates under your Apify account. Clockworks collection is billed separately. Reuse an existing dataset to avoid another collection charge.

## `searchQueries` (type: `array`):

Optional search variants. AI automatically creates up to three variants when this is empty. Other methods use the topic as entered. Collection stays within the candidate limit.

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

Full https://www.tiktok.com/@creator/video/123... URLs. Short share links and profile URLs are rejected. Required for audit; maximum 200 distinct videos.

## `datasetId` (type: `string`):

Choose the existing Apify dataset to analyze. Only read access is requested. Required when source is dataset.

## `videos` (type: `array`):

Paste TikTok video objects. Supports nested Clockworks fields and flattened exports. Required when source is inline. Strings, profile objects, and error records are reported as invalid.

## `maxCandidates` (type: `integer`):

Maximum source rows loaded. Live search may return fewer. For audits this must cover the number of distinct requested URLs.

## `maxResults` (type: `integer`):

Maximum ranked videos returned in search. Audit returns every requested URL unless the Actor's charge limit stops delivery.

## `minRelevance` (type: `number`):

0.7 selects directly relevant topics with AI analysis. Lower this to explore broader matches. Audit keeps every requested URL and marks filter failures.

## `rankingEngine` (type: `string`):

AI analysis provides relevance explanations and verified text excerpts, with no API key required in the hosted Actor's default configuration. Local semantic AI works without an external key. Lexical matches words only.

## `deepseekApiKey` (type: `string`):

Leave empty to use the hosted Actor's default AI. Advanced option: a DeepSeek API key, sent only to api.deepseek.com. Usage on your own key is paid by you. Never paste a key into captions or search terms.

## `includeKeywords` (type: `array`):

At least one term must occur in caption, hashtags, or supplied transcript. Matching ignores case and accents.

## `excludeKeywords` (type: `array`):

Reject search candidates containing any listed term. Audits retain the row with a filter reason.

## `language` (type: `string`):

Optional source-supplied language code, such as pt or en. Unknown language fails this filter. The Actor does not guess language.

## `minViews` (type: `integer`):

Unknown view counts fail this filter when it is greater than zero. Missing metrics remain null, never invented as zero.

## `publishedAfter` (type: `string`):

Optional inclusive calendar date in UTC, YYYY-MM-DD. Unknown dates fail this filter.

## `publishedBefore` (type: `string`):

Optional inclusive calendar date in UTC, YYYY-MM-DD. Unknown dates fail this filter.

## `upstreamMaxCostUsd` (type: `number`):

Maximum pay-per-event charge passed to the child Clockworks run. Its platform usage/storage may be additional. This is separate from the charge limit for this Actor.

## `upstreamTimeoutSecs` (type: `integer`):

Maximum collection time. Timed-out, failed, and aborted child runs are reported as partial; their results are never claimed to be complete.

## Actor input object example

```json
{
  "mode": "search",
  "query": "skincare routine for oily acne-prone skin",
  "source": "live",
  "searchQueries": [],
  "videoUrls": [],
  "videos": [],
  "maxCandidates": 30,
  "maxResults": 20,
  "minRelevance": 0.65,
  "rankingEngine": "deepseek",
  "includeKeywords": [],
  "excludeKeywords": [],
  "minViews": 0,
  "upstreamMaxCostUsd": 1,
  "upstreamTimeoutSecs": 600
}
```

# Actor output Schema

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

No description

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

No description

## `report` (type: `string`):

No description

## `preview` (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 = {
    "query": "skincare routine for oily acne-prone skin"
};

// Run the Actor and wait for it to finish
const run = await client.actor("heiman/tiktok-semantic-search-audit").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": "skincare routine for oily acne-prone skin" }

# Run the Actor and wait for it to finish
run = client.actor("heiman/tiktok-semantic-search-audit").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": "skincare routine for oily acne-prone skin"
}' |
apify call heiman/tiktok-semantic-search-audit --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,heiman/tiktok-semantic-search-audit"
        }
    }
}
```

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/VID6iulUBQccVJaag/builds/UpidGjRvlqcF1GN9R/openapi.json