# TikTok Keyword Suggestions Scraper (`benthepythondev/tiktok-keyword-suggestions-scraper`) Actor Collect ranked TikTok autocomplete suggestions from seed keywords with bounded alphabet, number and recursive expansion plus transparent frequency signals. - **URL**: https://apify.com/benthepythondev/tiktok-keyword-suggestions-scraper.md - **Developed by:** [Ben](https://apify.com/benthepythondev) (community) - **Categories:** Social media, Marketing, SEO tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.50 / 1,000 results 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 terms into ranked TikTok autocomplete suggestions without a TikTok login, browser runtime, residential proxy, or external API key. The TikTok Keyword Suggestions Scraper supports direct seed lookup, A-Z expansion, number expansion, bounded recursive discovery, deduplication, and a transparent cross-query frequency proxy. The Actor calls the public autocomplete preview resource used by TikTok search and returns one structured row per suggestion. It preserves TikTok's own source rank and metadata while clearly separating observed fields from derived signals. ### What can you use it for? - Discover the phrases TikTok currently suggests for a topic. - Expand a small seed list into long-tail keyword ideas. - Compare which suggestions recur across A-Z or recursive query variants. - Build a reviewed input list for content research or social listening. - Track how autocomplete suggestions change between scheduled snapshots. - Group suggestions by language, tokenization, or recall source. - Send ranked keyword tables to Google Sheets, Airtable, n8n, Make, or Zapier. The Actor does not claim to provide TikTok's private absolute search volume. `volume_proxy` is simply the number of queried variants in the current run that returned the same suggestion. It is useful as a relative recurrence signal within one controlled run, not as an official monthly-search estimate. ### Input ```json { "keywords": ["home decor"], "expandAlphabet": false, "expandNumbers": false, "expansionDepth": 0, "language": "en-US", "maxQueries": 10, "maxSuggestionsPerQuery": 10, "maxResults": 25, "deduplicateSuggestions": true } ```` #### Input fields | Field | Type | Default | Description | | --- | --- | --- | --- | | `keywords` | array | `["home decor"]` | Initial TikTok search terms. | | `expandAlphabet` | boolean | `false` | Add `a` through `z` to every seed. | | `expandNumbers` | boolean | `false` | Add `0` through `9` to every seed. | | `expansionDepth` | integer | `0` | Feed returned suggestions back into autocomplete, up to depth two. | | `language` | string | `en-US` | Request language preference. TikTok still controls localization. | | `maxQueries` | integer | `30` | Hard request budget for all seeds and expansions. | | `maxSuggestionsPerQuery` | integer | `10` | Maximum suggestions retained from each query. | | `maxResults` | integer | `100` | Maximum rows saved to the dataset. | | `deduplicateSuggestions` | boolean | `true` | Merge repeated suggestions and calculate `volume_proxy`. | Expansion can grow quickly. A single seed with A-Z expansion creates up to 27 initial requests before recursive expansion. Start with `maxQueries` between 10 and 30, inspect the results, and increase it only when the broader query tree is useful. ### Output ```json { "seed_keyword": "home decor", "request_query": "home decor", "source_queries": ["home decor"], "query_count": 1, "suggestion": "Home decor ideas", "normalized_suggestion": "home decor ideas", "group_id": "5160900346397932888", "rank": 1, "best_tiktok_rank": 1, "query_rank": 1, "expansion_depth": 0, "volume_proxy": 1, "language": "en", "words_source": "sug", "is_personalized": true, "recall_reasons": ["tiktok_orion_query", "tiktok_index_global_active_7d_query"], "cut_query_tokens": ["Home", "decor", "ideas"], "matched_ranges": [{"begin": 0, "end": 9}], "url": "https://www.tiktok.com/search?q=Home+decor+ideas", "scraped_at": "2026-07-11T10:30:00+00:00" } ``` #### Source fields - `suggestion` is the autocomplete phrase returned by TikTok. - `group_id` is the public suggestion group identifier when TikTok provides it. - `best_tiktok_rank` is the best position at which TikTok returned the phrase. - `language`, `words_source`, `is_personalized`, `recall_reasons`, `cut_query_tokens`, and `matched_ranges` are normalized from the response metadata. #### Run-derived fields - `seed_keyword` and `request_query` preserve how the phrase was discovered. - `source_queries` lists all query variants that returned a merged suggestion. - `query_count` and `volume_proxy` count those appearances within this run. - `expansion_depth` records the shallowest discovery depth. - `rank` is the final output order after sorting by frequency proxy, best TikTok rank, and phrase. No derived field is presented as official TikTok volume, trend score, or campaign performance. ### A practical keyword workflow 1. Start with three to ten narrow seed phrases. 2. Run without expansion and review TikTok's direct suggestions. 3. Enable A-Z expansion for the seeds that need broader long-tail coverage. 4. Keep recursive depth at zero or one unless a larger tree has a defined use. 5. Retain source queries and ranks so the discovery path stays auditable. 6. Review suggestions for relevance, safety, and language before using them downstream. 7. Append timestamped snapshots if suggestion changes matter over time. Autocomplete is a research signal, not an instruction to publish. A suggested phrase can be ambiguous, unsafe, misleading, or irrelevant to the intended audience. Keep a human review step. ### Integrations and scheduling Use an Apify Task to save a repeatable keyword configuration, then attach a schedule or webhook. Results can be downloaded as JSON, CSV, Excel, XML, RSS, or Parquet and routed to: - Google Sheets or Airtable for editorial review - n8n, Make, or Zapier for workflow triggers - BigQuery, Snowflake, PostgreSQL, or object storage for snapshots - a Python or JavaScript service through the Apify API - a manual content-research queue For monitoring, compare `normalized_suggestion` across runs and retain `scraped_at`. Do not overwrite the prior dataset if historical change is the objective. ### Pricing This Actor uses transparent pay-per-event pricing: - `$0.005` when the Actor starts. - `$0.0015` for each suggestion row saved to the default dataset. A 100-row run costs about `$0.155` in Actor charges before ordinary Apify platform usage. Duplicate appearances merged into one row are billed once. Requests, discarded empty records, and rows beyond `maxResults` do not create result charges. ### Reliability and limits The engine uses Chrome-compatible TLS impersonation and direct HTTP requests. It requires no proxy or browser. Each request has an explicit timeout and up to three bounded retries. Query count, recursive depth, per-query results, and total output are all capped. The Actor fails when TikTok returns no usable suggestions instead of reporting a successful empty dataset. That makes scheduled source changes visible. TikTok can change its public endpoint or localization behavior; report a reproducible input through the Actor's Issues tab if a previously working seed stops returning data. ### Responsible use Use this Actor for legitimate public-data research. Follow TikTok's terms, applicable law, and your organization's policies. Do not use the output for harassment, sensitive profiling, deceptive targeting, spam, or automated publication without review. Autocomplete can reflect current events, platform experiments, regional differences, and potentially sensitive phrases. Avoid treating it as an endorsement, factual statement, or demographic conclusion. ### Frequently asked questions #### Does it require a TikTok account? No. It uses a public autocomplete response and does not authenticate as a user. #### Is `volume_proxy` official TikTok search volume? No. It only counts how many request variants in the current run returned the same phrase. #### Does changing `language` guarantee country-specific results? No. It changes the request language preference. TikTok can also localize by network location and its own systems. The Actor does not claim country-pinned output because it does not spend residential proxy traffic. #### How many requests does A-Z expansion make? Up to 27 per seed: the original seed plus 26 letter variants. `maxQueries` remains the hard global cap. #### Why are some suggestions marked personalized on an anonymous request? That is the flag returned by TikTok's public resource. The Actor preserves it without claiming a logged-in user profile influenced the request. #### Can I schedule it? Yes. Save the input as an Apify Task, add a schedule, and compare timestamped datasets by `normalized_suggestion`. ### You might also like - [Pinterest Keyword Suggestions Scraper](https://apify.com/benthepythondev/pinterest-keyword-suggestions-scraper) for Pinterest autocomplete research. - [Pinterest Search Scraper](https://apify.com/benthepythondev/pinterest-search-scraper) for ranked Pinterest pin discovery. - [TikTok Scraper](https://apify.com/benthepythondev/tiktok-scraper) for broader public TikTok datasets. If the Actor saved time or replaced manual work, leave a Store review. Reviews help prioritize endpoint monitoring and useful field improvements. Keywords: TikTok keyword scraper, TikTok autocomplete API, TikTok keyword suggestions, TikTok SEO tool, TikTok search terms, TikTok content research, TikTok long-tail keywords, TikTok trend research, social media keyword scraper. ### Production workflow This Actor is designed for short-form video teams, social strategists, agencies and creator researchers. Start with one narrow topic, use bounded expansion to discover long-tail phrases, and compare repeated suggestions across query variants before assigning content ideas to a publishing calendar. Small, repeatable runs are easier to audit than occasional unlimited exports: they expose source changes quickly, reduce duplicate processing and keep automation costs predictable. Use the input defaults as a smoke test, then widen the query only after confirming that the returned fields match the downstream workflow. Treat each dataset row as source evidence captured at a point in time, not as a permanent fact. Preserve the canonical identifier and source URL, add the run timestamp in the receiving system, and deduplicate before writing to a CRM, spreadsheet, warehouse or alert channel. For recurring monitoring, compare the newest dataset with the previous successful run and send only additions or material changes onward. That pattern avoids repeated notifications and makes the automation more useful over time. ### Data quality and interpretation The primary output includes `seed_keyword`, `request_query`, `source_queries`, `query_count`, `suggestion`, `normalized_suggestion`, `group_id`, `rank`, `best_tiktok_rank`, `query_rank`, `expansion_depth`, `volume_proxy`. Availability depends on what the source publishes for a particular result. Empty values are retained as null or empty fields rather than invented. Search rank is source-specific and can change with language, geography, query wording and time. Validate critical decisions against the linked source page, especially when the data is used for outreach, compliance, pricing, routing or reporting. Use bounded inputs and respect the source's published interface. The Actor does not bypass logins or collect private account data. Avoid placing passwords, session cookies, personal access tokens or confidential records in Actor input. If a public source changes its response shape, attach a reproducible public input and run ID to an Actor issue so the parser can be updated without exposing private data. ### Automation and cost control The default dataset can be exported as JSON, CSV, Excel, XML or RSS and can be consumed through the Apify API. In Make, Zapier or n8n, start the Actor, wait for the run to finish, then read default-dataset items. In code, store the Actor run ID and dataset ID alongside the imported rows so every record remains traceable. Apply filters after collection only when the source cannot express them directly; source-side filtering usually reduces cost and noise. This Actor uses pay-per-event billing. A result event is charged only when a structured row is saved to the default dataset. Keep test runs small, estimate expected row volume before scheduling broad searches, and use platform spending limits for unattended workflows. Failed requests and empty searches should not create result events. ### Support and feedback If the Actor saves time in a real workflow, please leave a short Apify Store review describing the use case and the fields that were most useful. Reviews help other users evaluate the product and help prioritize maintenance. For support, open an Actor issue with the run ID, public input, expected behavior and one affected field. Do not include credentials or confidential information. # Actor input Schema ## `keywords` (type: `array`): Seed terms to send to TikTok autocomplete. ## `expandAlphabet` (type: `boolean`): Append a through z to each seed before querying. ## `expandNumbers` (type: `boolean`): Append zero through nine to each seed before querying. ## `expansionDepth` (type: `integer`): Feed returned suggestions back into autocomplete. Zero uses only the initial query set; one is usually enough for broader research. ## `language` (type: `string`): Accept-Language value used for the public TikTok request. Results can still reflect TikTok's own localization logic. ## `maxQueries` (type: `integer`): Hard request budget across seeds and all expansions. ## `maxSuggestionsPerQuery` (type: `integer`): Maximum TikTok suggestions retained from each request. ## `maxResults` (type: `integer`): Maximum suggestion rows saved to the dataset. ## `deduplicateSuggestions` (type: `boolean`): Merge the same suggestion across queries and report how often it appeared as volume\_proxy. ## Actor input object example ```json { "keywords": [ "home decor" ], "expandAlphabet": false, "expandNumbers": false, "expansionDepth": 0, "language": "en-US", "maxQueries": 10, "maxSuggestionsPerQuery": 10, "maxResults": 10, "deduplicateSuggestions": true } ``` # Actor output Schema ## `results` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "keywords": [ "home decor" ], "expandAlphabet": false, "expandNumbers": false, "expansionDepth": 0, "language": "en-US", "maxQueries": 10, "maxSuggestionsPerQuery": 10, "maxResults": 10, "deduplicateSuggestions": true }; // Run the Actor and wait for it to finish const run = await client.actor("benthepythondev/tiktok-keyword-suggestions-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "keywords": ["home decor"], "expandAlphabet": False, "expandNumbers": False, "expansionDepth": 0, "language": "en-US", "maxQueries": 10, "maxSuggestionsPerQuery": 10, "maxResults": 10, "deduplicateSuggestions": True, } # Run the Actor and wait for it to finish run = client.actor("benthepythondev/tiktok-keyword-suggestions-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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": [ "home decor" ], "expandAlphabet": false, "expandNumbers": false, "expansionDepth": 0, "language": "en-US", "maxQueries": 10, "maxSuggestionsPerQuery": 10, "maxResults": 10, "deduplicateSuggestions": true }' | apify call benthepythondev/tiktok-keyword-suggestions-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=benthepythondev/tiktok-keyword-suggestions-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Keyword Suggestions Scraper", "description": "Collect ranked TikTok autocomplete suggestions from seed keywords with bounded alphabet, number and recursive expansion plus transparent frequency signals.", "version": "1.0", "x-build-id": "xMjWC04mSLMowA6SH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/benthepythondev~tiktok-keyword-suggestions-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-benthepythondev-tiktok-keyword-suggestions-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/benthepythondev~tiktok-keyword-suggestions-scraper/runs": { "post": { "operationId": "runs-sync-benthepythondev-tiktok-keyword-suggestions-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/benthepythondev~tiktok-keyword-suggestions-scraper/run-sync": { "post": { "operationId": "run-sync-benthepythondev-tiktok-keyword-suggestions-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "keywords" ], "properties": { "keywords": { "title": "Seed keywords", "type": "array", "description": "Seed terms to send to TikTok autocomplete.", "default": [ "home decor" ], "items": { "type": "string" } }, "expandAlphabet": { "title": "A-Z expansion", "type": "boolean", "description": "Append a through z to each seed before querying.", "default": false }, "expandNumbers": { "title": "0-9 expansion", "type": "boolean", "description": "Append zero through nine to each seed before querying.", "default": false }, "expansionDepth": { "title": "Recursive expansion depth", "minimum": 0, "maximum": 2, "type": "integer", "description": "Feed returned suggestions back into autocomplete. Zero uses only the initial query set; one is usually enough for broader research.", "default": 0 }, "language": { "title": "Request language", "type": "string", "description": "Accept-Language value used for the public TikTok request. Results can still reflect TikTok's own localization logic.", "default": "en-US" }, "maxQueries": { "title": "Maximum query requests", "minimum": 1, "maximum": 500, "type": "integer", "description": "Hard request budget across seeds and all expansions.", "default": 30 }, "maxSuggestionsPerQuery": { "title": "Maximum suggestions per query", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum TikTok suggestions retained from each request.", "default": 10 }, "maxResults": { "title": "Maximum total results", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum suggestion rows saved to the dataset.", "default": 10 }, "deduplicateSuggestions": { "title": "Deduplicate suggestions", "type": "boolean", "description": "Merge the same suggestion across queries and report how often it appeared as volume_proxy.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```