# TikTok Search Scraper (`crawlerbros/tiktok-search-scraper`) Actor Scrape TikTok videos by keyword search. Extract full video metadata, author info, music, stats, and location data from TikTok search results. No cookies required. - **URL**: https://apify.com/crawlerbros/tiktok-search-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Social media, Videos - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 Search Scraper Search TikTok by keyword or phrase and collect full video metadata for each result. The actor uses TikTok's general search API and returns up to 500 results per query — including engagement stats, author profiles, music details, hashtags, mentions, and optional location tags (POI). No login, cookies, or proxy required. ### What this actor does - Accepts one or more search keywords or phrases and paginates through all result pages - Returns full post metadata for each video: caption, creation date, rank in results, and direct post URL - Captures engagement stats (views, likes, comments, shares) sourced from TikTok's `statsV2` field for accuracy on large accounts - Extracts author profile snapshot including username, display name, verification status, and avatar - Parses hashtags and @mentions directly from the post caption - Attaches music metadata (title, artist, original flag) and video technical details (resolution, duration) - Includes Point of Interest (POI) location data when the creator tagged a place - Empty fields are omitted ### Output per video - `postId` — unique TikTok video ID - `postUrl` — direct URL to the video - `caption` — full caption text - `query` — the search keyword that returned this post - `rank` — zero-based position in the search results for this query - `searchType` — always `"general"` - `author.id` — author's TikTok user ID - `author.secUid` — author's secondary unique ID - `author.username` — author handle - `author.displayName` — author display name - `author.verified` — whether the author is verified - `author.avatarUrl` — author profile image URL - `likeCount` — total likes - `commentCount` — total comments - `shareCount` — total shares - `playCount` — total plays/views - `createTime` — Unix timestamp of post creation - `music.id` — sound/music ID - `music.title` — sound title - `music.authorName` — sound creator name - `music.original` — whether it is an original sound - `hashtags` — array of hashtag names parsed from caption - `mentions` — array of @mention usernames parsed from caption - `poi.name` — location name (when present) - `poi.address` — location address (when present) - `poi.city` — city of the location (when present) - `poi.country` — country code of the location (when present) - `poi.category` — place category, e.g. Restaurant (when present) - `video.width` — video width in pixels - `video.height` — video height in pixels - `video.duration` — video duration in seconds - `video.playUrl` — streamable video URL (expires) - `video.cover` — cover/thumbnail image URL - `scrapedAt` — ISO 8601 timestamp of when the record was collected ### Input | Field | Type | Default | Description | |---|---|---|---| | `queries` | string[] | — | Search keywords or phrases to query TikTok for. Required. | | `maxResultsPerQuery` | integer | 30 | Maximum number of video results to collect per query (1–500). | #### Example: trending keyword search ```json { "queries": ["viral"], "maxResultsPerQuery": 50 } ```` #### Example: multi-keyword brand research ```json { "queries": ["nike running", "adidas shoes", "puma sports"], "maxResultsPerQuery": 100 } ``` #### Example: creator mention search ```json { "queries": ["@natgeo"], "maxResultsPerQuery": 30 } ``` #### Example: niche trend discovery ```json { "queries": ["cottagecore aesthetic", "dark academia"], "maxResultsPerQuery": 200 } ``` ### Use cases - **Content researchers** finding trending videos on any topic to inform editorial calendars - **Brand teams** monitoring mentions of their product or competitor names across TikTok - **Influencer agencies** discovering creators in niche categories via keyword search - **PR and comms teams** tracking buzz around a product launch, event hashtag, or campaign - **Academic researchers** building video datasets for studying TikTok content patterns - **E-commerce analysts** identifying UGC and product reviews relevant to a category ### FAQ **Q: Do I need a TikTok account, cookies, or a proxy?**\ A: No. The actor uses TikTok's public search API accessible to anonymous visitors. No authentication or proxy is required. **Q: What is the `statsV2` field and why does it matter?**\ A: TikTok's standard integer stats overflow at approximately 2 billion (signed 32-bit limit). The `statsV2` field stores counts as strings, providing accurate numbers for large creators. The actor always reads from `statsV2` first. **Q: Are video and cover image URLs permanent?**\ A: No. TikTok's CDN URLs are signed and expire, typically within 24 hours. Use `postUrl` as the stable reference to the video. Download or cache media promptly after scraping. **Q: Can I search for a specific creator's content?**\ A: Use `@username` as a query (e.g. `@khaby.lame`). Results include posts that mention that creator, though it is not equivalent to fetching their profile feed directly. **Q: What is the `poi` field?**\ A: Point of Interest — the location tag a creator attaches to a post. It only appears when the creator tagged a specific place. It includes name, city, country, and category. **Q: How many results can I get per query?**\ A: Up to 500. TikTok returns approximately 12 results per search page and the actor paginates automatically until the limit or `has_more: false` is reached. **Q: Why might I get fewer results than my `maxResultsPerQuery` setting?**\ A: TikTok search has a finite result pool per query, typically 50–200 unique videos. Once TikTok signals no more results, the actor stops regardless of the limit. **Q: Can I search in a specific language or country?**\ A: Queries can be in any language. The results reflect TikTok's global index for that keyword. Region targeting is not currently supported as a direct input parameter. ### Related TikTok Scrapers Build a complete TikTok data pipeline with our full suite: | Scraper | URL | |---|---| | TikTok Post Scraper | https://apify.com/crawlerbros/tiktok-post-scraper | | TikTok Profile Scraper | https://apify.com/crawlerbros/tiktok-profile-scraper | | TikTok Comments Scraper | https://apify.com/crawlerbros/tiktok-comments-scraper | | TikTok Hashtag Scraper | https://apify.com/crawlerbros/tiktok-hashtag-scraper | | TikTok Music Scraper | https://apify.com/crawlerbros/tiktok-music-scraper | | TikTok Transcript Scraper | https://apify.com/crawlerbros/tiktok-transcript-scraper | | TikTok Followers Scraper | https://apify.com/crawlerbros/tiktok-followers-scraper | | TikTok Mention Scraper | https://apify.com/crawlerbros/tiktok-mention-scraper | | TikTok Profile Mention Scraper | https://apify.com/crawlerbros/tiktok-profile-mention-scraper | | TikTok Playlist Scraper | https://apify.com/crawlerbros/tiktok-playlist-scraper | | TikTok Explore Scraper | https://apify.com/crawlerbros/tiktok-explore-scraper | | TikTok For You Scraper | https://apify.com/crawlerbros/tiktok-for-you-scraper | | TikTok Downloader | https://apify.com/crawlerbros/tiktok-downloader-api | | TikTok Ads Library Scraper | https://apify.com/crawlerbros/tiktok-ads-library-scraper-pro | | TikTok Top Ads Scraper | https://apify.com/crawlerbros/tiktok-top-ads-scraper | | TikTok Hashtag Trends Scraper | https://apify.com/crawlerbros/tiktok-hashtag-trends-scraper | | TikTok LIVE Scraper | https://apify.com/crawlerbros/tiktok-live-scraper | # Actor input Schema ## `queries` (type: `array`): List of search keywords or phrases to scrape TikTok videos for. ## `maxResultsPerQuery` (type: `integer`): Maximum number of video results to collect per search query. ## Actor input object example ```json { "queries": [ "cooking recipes", "travel vlog", "@khaby.lame" ], "maxResultsPerQuery": 10 } ``` # Actor output Schema ## `data` (type: `string`): Dataset containing one row per TikTok video result. Each row includes postId, query, rank, caption, engagement stats (playCount, likeCount, etc.), author snapshot, music metadata, video technical details, hashtags, mentions, and optional poi (location tag). # 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 = { "queries": [ "viral" ], "maxResultsPerQuery": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/tiktok-search-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 = { "queries": ["viral"], "maxResultsPerQuery": 10, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/tiktok-search-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 '{ "queries": [ "viral" ], "maxResultsPerQuery": 10 }' | apify call crawlerbros/tiktok-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/tiktok-search-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Search Scraper", "description": "Scrape TikTok videos by keyword search. Extract full video metadata, author info, music, stats, and location data from TikTok search results. No cookies required.", "version": "1.0", "x-build-id": "LQr6mBrESYIBjrwXP" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~tiktok-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-tiktok-search-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/crawlerbros~tiktok-search-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-tiktok-search-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/crawlerbros~tiktok-search-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-tiktok-search-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": [ "queries" ], "properties": { "queries": { "title": "Search Queries", "type": "array", "description": "List of search keywords or phrases to scrape TikTok videos for.", "items": { "type": "string" } }, "maxResultsPerQuery": { "title": "Max Results Per Query", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of video results to collect per search query.", "default": 30 } } }, "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 } } } } } } } } } } ```