# TikTok Keyword Suggestions Scraper (`automation-lab/tiktok-keyword-suggestions`) Actor

Expand seed topics into ranked TikTok autocomplete suggestions with query context and public metadata for social SEO and content planning. Search volume is excluded.

- **URL**: https://apify.com/automation-lab/tiktok-keyword-suggestions.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Social media, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.12 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## TikTok Keyword Suggestions Scraper

Turn seed topics into ranked **TikTok keyword suggestions** for social SEO, short-form video ideation, and repeatable content planning. The Actor calls TikTok's anonymous search-preview data surface and exports each autocomplete phrase with its returned rank, query context, search link, and available public metadata.

It does **not** estimate or claim search volume. TikTok's preview response does not provide volume, so the output keeps source rank and public metadata separate from unsupported estimates.

### What does TikTok Keyword Suggestions Scraper do?

Provide plain keywords, TikTok search URLs, or both. The Actor extracts the search URL query, optionally expands each seed, requests autocomplete suggestions, deduplicates phrases within each seed, and saves typed rows to the default dataset.

Use a base query for a quick snapshot, A–Z or A–Z/0–9 suffixes for long-tail research, or question prefixes for educational content ideas. `maxItems` places a hard limit on saved results.

### Who is it for?

- Social SEO specialists building topic and caption research sheets.
- Creators turning broad themes into specific video ideas.
- Content strategists comparing autocomplete snapshots on a schedule.
- Agencies preparing repeatable briefs across several client topics.
- Data teams feeding public phrase suggestions into spreadsheets or pipelines.

### Why use this Actor?

The dataset preserves both the original seed and the exact expansion query, so every phrase has traceable context. It also distinguishes TikTok's per-query position (`queryRank`) from the deduplicated order collected for a seed (`seedRank`).

The implementation uses lightweight HTTP requests rather than loading video pages or downloading media. Requests are sequential, bounded, and retried only a limited number of times after upstream failures.

### What data can I extract?

| Field | Meaning |
| --- | --- |
| `seedKeyword` | Original keyword or query extracted from a TikTok search URL |
| `query` | Exact base or expansion query sent to TikTok |
| `suggestion` | Autocomplete phrase returned by TikTok |
| `normalizedSuggestion` | Normalized phrase used for deduplication |
| `queryRank` | One-based position in the source response for this query |
| `seedRank` | One-based unique result order for the seed |
| `searchUrl` | TikTok search URL for the suggestion |
| `region`, `language` | Request hints used for the result |
| `groupId`, `wordsSource`, `suggestionType` | Public source metadata when returned |
| `cutQuery` | Source-provided tokenized phrase parts |
| `recallReason` | Source recall labels when returned |
| `isPersonalized`, `isHistorySuggestion` | Source flags when returned |
| `fetchedAt` | ISO timestamp for the extraction |

Nullable metadata stays `null` when TikTok omits it.

### How to get started

1. Open the Actor input page.
2. Add one or more real topics under **Seed keywords**, or add TikTok search URLs.
3. Keep **Base suggestions only** for a fast first run.
4. Set the global maximum number of results.
5. Choose region and language hints.
6. Start the run and open the **Suggestions** dataset view.
7. Export the dataset as JSON, CSV, Excel, XML, or RSS through Apify.

The prefilled `skincare routine` and `meal prep` topics provide a useful first run.

### Input parameters

| Input | Type | Default | Notes |
| --- | --- | --- | --- |
| `keywords` | string array | prefilled topics | Up to 100 unique, non-empty seeds |
| `searchUrls` | request list | none | TikTok `/search?q=...` URLs |
| `expansionMode` | enum | `none` | `none`, `alphabet`, `alphanumeric`, or `questions` |
| `maxSuggestionsPerQuery` | integer | `10` | Between 1 and 10 |
| `maxItems` | integer | `20` | Global output limit from 1 to 5,000 |
| `region` | string | `US` | Two-letter request hint, not guaranteed proxy geography |
| `language` | string | `en-US` | Language hint such as `en`, `en-US`, or `es` |

At least one valid keyword or TikTok search URL is required. Invalid URLs without a `q` parameter do not become seeds.

### Expansion modes

- `none`: one TikTok request for each seed.
- `alphabet`: base query plus `seed a` through `seed z`.
- `alphanumeric`: base query plus A–Z and 0–9 suffixes.
- `questions`: base query plus `how`, `what`, `when`, `where`, and `why` prefixes.

Expansion increases request count and can still return duplicate or naturally empty responses. Results are deduplicated independently for each seed. The Actor stops scheduling work when `maxItems` is reached.

### Example input

```json
{
  "keywords": ["skincare routine", "meal prep"],
  "expansionMode": "none",
  "maxSuggestionsPerQuery": 10,
  "maxItems": 20,
  "region": "US",
  "language": "en-US"
}
```

A source-URL workflow can instead use:

```json
{
  "searchUrls": [
    { "url": "https://www.tiktok.com/search?q=budget%20travel" }
  ],
  "maxItems": 10
}
```

### Example output

This abbreviated row reflects the current output shape from a local source-backed run:

```json
{
  "seedKeyword": "meal prep",
  "query": "meal prep",
  "suggestion": "meal prep ideas",
  "normalizedSuggestion": "meal prep ideas",
  "queryRank": 1,
  "seedRank": 1,
  "source": "tiktok_search_preview",
  "searchUrl": "https://www.tiktok.com/search?q=meal%20prep%20ideas",
  "region": "US",
  "language": "en-US",
  "groupId": "2042627834678721152",
  "wordsSource": "sug",
  "suggestionType": null,
  "cutQuery": ["meal", "prep", "ideas"],
  "recallReason": "tiktok_index_global_active_7d_query",
  "isPersonalized": true,
  "isHistorySuggestion": false,
  "fetchedAt": "2026-09-08T12:00:00.000Z"
}
```

Exact phrases and metadata change as TikTok changes its public suggestions.

### How much does it cost to extract TikTok keyword suggestions?

Pay-per-event pricing has a **$0.005 start fee** plus the active tier's price for each unique suggestion saved. At the BRONZE rate of **$0.00186 per suggestion**:

- 10 suggestions cost about **$0.0236** including the start fee.
- 100 suggestions cost about **$0.191** including the start fee.
- 1,000 suggestions cost about **$1.865** including the start fee.

Higher platform tiers receive lower per-suggestion rates. Failed, duplicate, empty, and unsaved candidate rows do not create item charges. Apify compute is included in pay-per-event pricing; check the live pricing tab for your tier before a large run.

### Schedule recurring social SEO research

Create an Apify Schedule with stable seeds and `expansionMode: "none"` for compact snapshots. Export each run to your warehouse, compare by `normalizedSuggestion`, and identify added, removed, or rank-shifted phrases downstream.

The Actor reports the current response only. It does not maintain history, calculate changes, or send alerts itself. Apify integrations or your own workflow should perform those steps.

### Export to spreadsheets and data pipelines

Use Apify's dataset integrations to send rows to Google Sheets, Make, Zapier, webhooks, or cloud storage. A practical flow is:

1. Run broad seeds in base mode.
2. Select promising returned phrases.
3. Run selected phrases with alphabet expansion.
4. Export `seedKeyword`, `query`, `suggestion`, and ranks.
5. Add editorial priority and campaign ownership in your destination system.

CSV is convenient for editorial review; JSON preserves booleans, arrays, and null values.

### Run through the Apify API with cURL

Replace `YOUR_TOKEN` with your Apify API token:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~tiktok-keyword-suggestions/runs?token=YOUR_TOKEN&waitForFinish=120" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["home workout"],"expansionMode":"none","maxItems":10}'
```

Fetch results from the run's `defaultDatasetId`, or use the synchronous dataset-items endpoint when appropriate.

### JavaScript API example

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/tiktok-keyword-suggestions').call({
  keywords: ['small business marketing'],
  expansionMode: 'alphabet',
  maxItems: 50,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Python API example

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("automation-lab/tiktok-keyword-suggestions").call(run_input={
    "keywords": ["budget travel"],
    "expansionMode": "questions",
    "maxItems": 30,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with MCP and AI agents

Add the Actor to Claude Code through Apify MCP:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/tiktok-keyword-suggestions"
```

For **Claude Desktop**, **Cursor**, and **VS Code**, add this equivalent JSON configuration to the client's MCP settings:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/tiktok-keyword-suggestions"
    }
  }
}
```

Example prompts:

- "Find current TikTok autocomplete phrases for meal prep and home workouts."
- "Expand small business marketing with A–Z suffixes and return at most 50 rows."
- "Use this TikTok search URL as a seed and group the results by exact query."

### Limits and reliability

TikTok can change, throttle, localize, or remove its anonymous preview endpoint. The Actor uses bounded retries and fails visibly if the source response is blocked or malformed; it does not turn an upstream failure into a successful empty dataset.

Region and language are request hints. They do not guarantee country-specific output because the Actor does not automatically purchase or select a residential proxy. Autocomplete is dynamic, and repeated runs can differ. Some valid topics naturally return few or no suggestions.

The Actor does not scrape videos, profiles, comments, hashtags, engagement metrics, trend history, or search volume.

### Responsible use and legality

Only public anonymous suggestion data is requested. Use the output in accordance with TikTok's terms, applicable law, and your organization's policies. Avoid excessive expansion, respect intellectual property, and do not use suggestions to infer sensitive traits about individuals.

You are responsible for deciding whether your intended collection and downstream use are lawful. This Actor is a technical data-extraction tool, not legal advice.

### Troubleshooting

**Why did my run return no results?**

Check that the seed is a public, meaningful topic. Try base mode with a common phrase. If TikTok is temporarily throttling or changing its response, rerun later rather than increasing expansion immediately.

**Why does a TikTok search URL not work?**

It must use `tiktok.com/search` and include a non-empty `q` query parameter. Copy the full URL rather than a generic TikTok home page.

**Why are there fewer rows than `maxItems`?**

`maxItems` is a ceiling, not a promise. TikTok may return fewer suggestions, and duplicates within the same seed are saved only once.

### FAQ

**Does this include TikTok search volume?** No. The public preview response does not provide search volume, and the Actor does not invent a volume proxy.

**Is `queryRank` a volume score?** No. It is the phrase's one-based position in the exact autocomplete response.

**Can I combine keywords and search URLs?** Yes. Valid seeds from both inputs are normalized and deduplicated.

**Can I force results from a country?** No. `region` is a source request hint, not a guarantee of network geography.

**Are duplicates charged?** No. An item event is charged only for a unique row accepted and saved for a seed.

### Related automation-lab Actors

Use [TikTok Comments Scraper](https://apify.com/automation-lab/tiktok-comments-scraper) when your workflow starts from known videos and needs public comment records. Use [TikTok Trends Scraper](https://apify.com/automation-lab/tiktok-trends-scraper) for supported trend-list workflows rather than autocomplete expansion.

These Actors solve separate jobs. This Actor remains focused on seed-to-autocomplete discovery and can provide phrases for downstream research.

# Actor input Schema

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

Topics to expand into TikTok autocomplete suggestions. Provide keywords, search URLs, or both (maximum 100 unique seeds).

## `searchUrls` (type: `array`):

TikTok search URLs whose q query parameter becomes a seed, for example https://www.tiktok.com/search?q=home%20workout.

## `expansionMode` (type: `string`):

Base only makes one request per seed. Alphabet and alphanumeric append suffixes for long-tail discovery. Questions prepend common question words.

## `maxSuggestionsPerQuery` (type: `integer`):

Maximum suggestions requested from TikTok for each base or expansion query. TikTok currently returns at most about 10.

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

Stop after this many unique suggestion rows across all seeds.

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

Two-letter region hint sent to TikTok, such as US or GB. This is not a guarantee of proxy geography.

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

Language header and TikTok browser-language hint, such as en-US or es.

## Actor input object example

```json
{
  "keywords": [
    "skincare routine",
    "meal prep"
  ],
  "expansionMode": "none",
  "maxSuggestionsPerQuery": 10,
  "maxItems": 20,
  "region": "US",
  "language": "en-US"
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing all unique suggestion rows.

# 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": [
        "skincare routine",
        "meal prep"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/tiktok-keyword-suggestions").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": [
        "skincare routine",
        "meal prep",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/tiktok-keyword-suggestions").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": [
    "skincare routine",
    "meal prep"
  ]
}' |
apify call automation-lab/tiktok-keyword-suggestions --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/tiktok-keyword-suggestions"
        }
    }
}
```

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/zP2VK1rfhQdqhUAT1/builds/OshrdOfoSge12mRPg/openapi.json