TikTok Keyword Search & Discovery Scraper: MCP config, n8n workflow and API

{
  "searchType": "videos",
  "queries": [
    "viral"
  ],
  "maxResultsPerQuery": 3,
  "sortBy": "relevance",
  "publishedWithin": "all",
  "excludeAds": false,
  "uniqueAuthors": false,
  "enableExpansion": false,
  "expansionSources": [
    "suggestions",
    "hashtags",
    "sounds"
  ],
  "maxExpansionQueriesPerSeed": 3,
  "includeHashtagMetadata": true
}

---
name: tiktok-keyword-search-and-discovery-scraper
description: "Search TikTok by keyword or phrase and get matching videos with engagement stats, author profiles, music metadata, hashtags, and location tags, with optional discovery expansion for more results. Runs the Apify Actor vexaloom-labs/tiktok-keyword-search-and-discovery-scraper. Use when the user needs TikTok data with fields such as postId, query, rank, searchType, caption, createdAt and an Apify token is available."
compatibility: "Needs network access, curl, and an APIFY_TOKEN environment variable. Runs are billed to the token owner's Apify account."
metadata:
  actor: "vexaloom-labs/tiktok-keyword-search-and-discovery-scraper"
  store-url: "https://apify.com/vexaloom-labs/tiktok-keyword-search-and-discovery-scraper"
---

# TikTok Keyword Search & Discovery Scraper

Use this skill to fetch TikTok data with the Apify Actor `vexaloom-labs/tiktok-keyword-search-and-discovery-scraper` and work with the returned rows.

## Before running

1. Check that `APIFY_TOKEN` is set in the environment. Never print it or write it to a file.
2. Build `input.json` from the user's request using the fields below. Keep limits small for a first run.
3. Confirm the search terms or URLs with the user if the request is ambiguous.

## Input fields

| Field | Type | Meaning |
| --- | --- | --- |
| `searchType` | one of `videos`, `photos`, `hashtags`, required | Videos: keyword video search. Photos: slideshow/photo search. Hashtags: hashtag metadata plus its top videos (uses the Hashtags field). |
| `queries` | array | Keywords or phrases to search for (searchType=videos or photos). Each query is searched independently. |
| `maxResultsPerQuery` | integer | Maximum posts to collect per query or hashtag, before filters. TikTok itself usually returns about 150-220 posts per query even when you ask for more. For hashtags, the metadata row is not counted against this limit. |
| `sortBy` | one of `relevance`, `mostLiked`, `mostViewed`, `newest` | Client-side sort applied after collecting results. TikTok's web search does not support server-side sorting, so this only reorders the posts TikTok returned. |
| `publishedWithin` | one of `all`, `day`, `week`, `month`, `3months`, `6months` | Client-side filter that drops posts older than the selected window, based on each post's creation time. |
| `excludeAds` | boolean | Drop posts TikTok flags as paid advertisements. |
| `uniqueAuthors` | boolean | Keep at most one post per creator, so the results read like a creator shortlist. When a sort is selected, the top-ranked post from each creator is kept. |
| `enableExpansion` | boolean | After each keyword search, run extra searches derived from its own results: related searches, its top hashtags and its most-reused sound. Increases run time and the number of posts found. Videos only. |
| `expansionSources` | array | Which discovery sources to use when expansion is on. All three can be combined. |
| `maxExpansionQueriesPerSeed` | integer | Maximum number of extra searches to run per keyword when expansion is on. Each one costs roughly as much run time as the original search. |
| `includeHashtagMetadata` | boolean | For hashtag searches: emit a metadata row with the hashtag's post count, view count, description and images. Also attaches metadata to hashtag-expansion posts when expansion is on. |

Example `input.json` (the Actor's published prefill):

```json
{
  "searchType": "videos",
  "queries": [
    "viral"
  ],
  "maxResultsPerQuery": 3,
  "sortBy": "relevance",
  "publishedWithin": "all",
  "excludeAds": false,
  "uniqueAuthors": false,
  "enableExpansion": false,
  "expansionSources": [
    "suggestions",
    "hashtags",
    "sounds"
  ],
  "maxExpansionQueriesPerSeed": 3,
  "includeHashtagMetadata": true
}
```

## Run

```bash
curl -sS -X POST "https://api.apify.com/v2/acts/vexaloom-labs~tiktok-keyword-search-and-discovery-scraper/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d @input.json > results.json
```

The call waits for the run to finish and returns the dataset items as a JSON array. If the run needs more than 300 seconds the API answers with HTTP 408; then start the run with `POST /v2/acts/vexaloom-labs~tiktok-keyword-search-and-discovery-scraper/runs`, poll `GET /v2/actor-runs/{runId}` until `SUCCEEDED`, and read `GET /v2/datasets/{defaultDatasetId}/items`.

## Output

Each item is one record. Published fields include: `postId`, `query`, `rank`, `searchType`, `caption`, `createdAt`, `author`, `playCount`, `likeCount`, `commentCount`, `shareCount`, `postUrl`, `hashtagMetadata`.

Summarise what was found, cite the record URLs when present, and say how many items came back. Do not invent values for empty fields.