# Advanced TikTok User Search Scraper (`novi/tiktok-user-search`) Actor
Scrape TikTok user profiles based on keyword searches. Extract detailed data including follower counts, bio links, author IDs, and more, with advanced filtering options.
- **URL**: https://apify.com/novi/tiktok-user-search.md
- **Developed by:** [Novi](https://apify.com/novi) (community)
- **Categories:** Automation, Social media, News
- **Stats:** 47 total users, 7 monthly users, 100.0% runs succeeded, 2 bookmarks
- **User rating**: 1.00 out of 5 stars
## Pricing
from $2.00 / 1,000 each profiles
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/platform/actors/running/actors-in-store#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
This is a TikTok scraper that helps you extract user profile data. You can give it a list of keywords, and it will
search for TikTok users matching your criteria.
One of the best features is that you can deeply filter your target audience by their follower count, verification
status, and specific profile fields.
You also **don't need to pay for proxies**, which saves you money.
### Features
- Search for TikTok users using a list of keywords.
- Automatically handles pagination to scrape deep into the search results until your `maxItems` limit is reached.
- Filter your searches by **Follower Range** (e.g., "Zero to 1k", "Over 100k").
- Filter searches by **Profile Type** (e.g., target only "VERIFIED" users).
- Filter searches by **Search Field** (e.g., strictly match by "USERNAME").
- Filter searches by a specific country or region using ISO 3166-1 alpha-2 codes.
- Runs without needing separate proxies.
- (Advanced) Use your own JavaScript code (`customMapFunction`) to reformat the output data on the fly.
- Only scrapes public data.
- Access the results using the Apify SDK or REST API.
### How to Use It
To learn the basics of how to run this tool, the best place to start is
the [official Apify guide on running actors](https://docs.apify.com/platform/actors/running).
### Support
If you run into any trouble or have questions, you can file an issue under the "Issues" tab here on the actor page or
ask the community on the Apify Discord server.
### Bugs and Updates
This actor is actively developed. We keep it updated to fix any bugs and make sure it keeps working as TikTok changes.
It's built to be light on memory and uses optimized concurrent processing (p-limit) so you can scrape a lot of data
efficiently.
### Input Settings
Here is a breakdown of the settings you can configure for the scraper based on its schema.
| Field | Type | Description |
|-----------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| **`keywords`** | Array (of strings) | A list of search terms. Your keywords will apply to search users on TikTok. |
| **`maxItems`** | Number | Maximum number of items on output for each query. We will try to scrape and paginate until the result count is greater or equal to this limit. |
| **`followerRange`** | String | Filter users by follower count. Options: `DEFAULT`, `TO_1K`, `TO_10K`, `TO_100K`, `OVER_100K`. |
| **`profileType`** | String | Filter by profile status. Options: `DEFAULT` or `VERIFIED`. |
| **`searchField`** | String | Specify where to search the keyword. Options: `DEFAULT` or only `USERNAME`. |
| **`location`** | String | Enables the actor to retrieve the results from a specific region/location, given by an ISO 3166-1 alpha-2 country code (Default: "US"). |
| **`customMapFunction`** | String | (Advanced) Function that takes each output object as an argument and returns mapped data. |
| **`includeSearchKeywords`** | Boolean | If checked, a field will be added to each user item showing the search keyword that was used to find it. |
### Input Examples
Here is how you can configure the JSON input to run a specific user search:
**Targeting Verified Tech Reviewers in the US**
```json
{
"keywords": [
"tech reviewer",
"gadget unboxing"
],
"maxItems": 200,
"followerRange": "DEFAULT",
"profileType": "VERIFIED",
"searchField": "USERNAME",
"location": "US",
"includeSearchKeywords": true,
"customMapFunction": "(object) => { return {...object} }"
}
```
### Output Examples
```json
[
{
"accept_private_policy": false,
"account_labels": null,
"ad_cover_url": null,
"advance_feature_item_order": null,
"advanced_feature_info": null,
"authority_status": 0,
"avatar_168x168": {
"height": 720,
"uri": "tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"url_list": [
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-006823449c4&x-expire",
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a699200"
],
"url_prefix": null,
"width": 720
},
"avatar_300x300": {
"height": 720,
"uri": "tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"url_list": [
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"https://p19-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94"
],
"url_prefix": null,
"width": 720
},
"avatar_larger": {
"height": 720,
"uri": "tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"url_list": [
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"https://p19-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94"
],
"url_prefix": null,
"width": 720
},
"avatar_medium": {
"height": 720,
"uri": "tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"url_list": [
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"https://p19-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94"
],
"url_prefix": null,
"width": 720
},
"avatar_thumb": {
"height": 720,
"uri": "tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"url_list": [
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"https://p19-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94"
],
"url_prefix": null,
"width": 720
},
"avatar_uri": "tos-alisg-avt-0068/e4a6cc744c78453020a994ddff713e94",
"aweme_count": 39,
"block_status": 0,
"bold_fields": null,
"can_message_follow_status_list": [
0,
1,
2,
4
],
"can_set_geofencing": null,
"cha_list": null,
"comment_filter_status": 0,
"comment_setting": 0,
"commerce_user_level": 0,
"cover_url": null,
"custom_verify": "",
"cv_level": "",
"download_prompt_ts": 0,
"enable_direct_message": true,
"enabled_filter_all_comments": false,
"enterprise_verify_reason": "",
"events": null,
"fake_data_info": {},
"fb_expire_time": 0,
"follow_status": 0,
"follower_count": 27025,
"follower_status": 0,
"followers_detail": null,
"following_count": 1591,
"friends_status": 0,
"geofencing": null,
"hide_search": false,
"homepage_bottom_toast": null,
"ins_id": "",
"is_ad_fake": false,
"is_block": false,
"is_discipline_member": false,
"is_mute": 0,
"is_mute_lives": 0,
"is_mute_non_story_post": 0,
"is_mute_story": 0,
"is_private_account": 0,
"is_star": false,
"item_list": null,
"live_agreement": 0,
"live_commerce": false,
"live_verify": 0,
"mention_status": 1,
"mutual_relation_avatars": null,
"name_field": "unique_id",
"need_points": null,
"need_recommend": 0,
"nickname": "Anh Thơ",
"original_musician": {
"digg_count": 0,
"music_count": 0,
"music_used_count": 0,
"new_release_clip_ids": null
},
"platform_sync_info": null,
"prevent_download": false,
"relative_users": null,
"reply_with_video_flag": 4,
"room_id": 0,
"room_id_str": "0",
"search_highlight": null,
"search_user_desc": "Anh Thơ",
"search_user_name": "ther2kk",
"sec_uid": "MS4wLjABAAAA9mLfxX0JlzPkURXkTM0DNk3Upf-qWzhr0QQa8V-51q4MnJyInb_aQ_K-AcTVQj29",
"secret": 0,
"shield_comment_notice": 0,
"shield_digg_notice": 0,
"shield_edit_field_info": null,
"shield_follow_notice": 0,
"short_id": "0",
"show_image_bubble": false,
"special_account": {
"special_account_list": null
},
"special_lock": 1,
"status": 1,
"stitch_setting": 0,
"story_status": 0,
"total_favorited": 129261,
"type_label": null,
"uid": "7055936450743698434",
"unique_id": "ther2kk",
"user_canceled": false,
"user_mode": 1,
"user_now_pack_info": {},
"user_period": 0,
"user_profile_guide": null,
"user_rate": 1,
"user_spark_info": {},
"user_tags": null,
"verification_type": 1,
"verify_info": "",
"video_icon": {
"height": 720,
"uri": "",
"url_list": [],
"url_prefix": null,
"width": 720
},
"white_cover_url": null,
"with_commerce_entry": false
}
]
```
### During the Run and Getting Results
While it's running, the tool will log what it's doing in the console, including the current keyword being processed and
the pagination cursor status. If you give it a bad input (like an unsupported location), it will stop and post an error
message explaining what went wrong.
Your results are saved in a dataset. You can download them as JSON, CSV, Excel, etc., from the "Storage" tab, or access
them using the API.
### Limitations
- This scraper only gets public user data. It cannot access private accounts or data that isn't public.
- You must use the scraper in a way that respects TikTok's terms of use.
*(Note: Unlike older versions, this scraper **fully supports pagination** and will automatically fetch subsequent pages
until `maxItems` is met or no more data is available!)*
### Scrape any TikTok data you need with dedicated scrapers
If you want to get specific data from TikTok, you can use the scrapers below. Each scraper is made to help you get
different kinds of TikTok data, like hashtags, search results, profiles, or everything at once. You can look at them to
see which one you need.
| Scraper | Link |
|----------------------------|-------------------------------------------------------------------------------------|
| 👥 TikTok Followers API | [TikTok Followers API](https://apify.com/novi/tiktok-followers-api?fpr=7hce1m) |
| 🎙 TikTok Comment API | [TikTok Comment API](https://apify.com/novi/tiktok-comment-api?fpr=7hce1m) |
| 📹 TikTok Trend API | [TikTok Trend API](https://apify.com/novi/tiktok-trend-api?fpr=7hce1m) |
| 🔍 TikTok Search API | [TikTok Search API](https://apify.com/novi/tiktok-search-api?fpr=7hce1m) |
| 🧛 TikTok User API | [TikTok User API](https://apify.com/novi/tiktok-user-api?fpr=7hce1m) |
| 🎸 TikTok Music API | [TikTok Music API](https://apify.com/novi/tiktok-sound-api?fpr=7hce1m) |
| 🧛 TikTok User Info API | [TikTok User Info API](https://apify.com/novi/tiktok-user-info-api?fpr=7hce1m) |
| #️⃣ TikTok Hashtag API | [TikTok Hashtag API](https://apify.com/novi/tiktok-hashtag-api?fpr=7hce1m) |
| 🛍 TikTok Shop API | [TikTok Shop API](https://apify.com/novi/tiktok-shop-scraper?fpr=7hce1m) |
| 🐦 Twitter - X.com Scraper | [🐦 Twitter - X.com Scraper](https://apify.com/xtdata/twitter-x-scraper?fpr=7hce1m) |
### Ethical Use and Data Practices
We designed this tool to be fair and responsible.
- It **does not require a login**. This means it only accesses data that is already public for everyone to see, just
like a normal visitor.
- The tool only scrapes publicly available information and does not collect sensitive personal data or anything behind a
login wall.
- Because this runs on Apify (an EU-based company), it is designed to follow EU data rules (like GDPR).
- The scraper also runs gently to make sure it doesn't overload TikTok's servers.
For more on this topic, Apify wrote a good article about the legality of web
scraping:
# Actor input Schema
## `keywords` (type: `array`):
Your keyword will apply to search users. As for your query's format, you can use any query that works on TikTok.
## `maxItems` (type: `integer`):
Maximum number of items that you want as output. Please note that we don't hard limit the result. We will try to scrape until result count is greater or equal limit.
## `followerRange` (type: `string`):
Follower Range, can be empty.
## `profileType` (type: `string`):
Default or VERIFIED
## `searchField` (type: `string`):
Search by default or only username.
## `location` (type: `string`):
Enables the actor to retrieve the results from that specific region/location, given by an ISO 3166-1 alpha-2 country code.
## `customMapFunction` (type: `string`):
Function that takes each of the objects as argument and returns data that will be mapped by the function itself. This function is not intended for filtering, please don't use it for filtering purposes or you will get banned automatically.
## `includeSearchKeywords` (type: `boolean`):
If selected, a field will be added to each tweets about the search keyword that was used to find it.
## Actor input object example
```json
{
"keywords": [
"cat",
"lover"
],
"maxItems": 20,
"followerRange": "DEFAULT",
"profileType": "DEFAULT",
"searchField": "DEFAULT",
"location": "US",
"customMapFunction": "(object) => { return {...object} }"
}
```
# 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": [
"cat",
"lover"
],
"maxItems": 20,
"followerRange": "DEFAULT",
"profileType": "DEFAULT",
"searchField": "DEFAULT",
"location": "US",
"customMapFunction": (object) => { return {...object} }
};
// Run the Actor and wait for it to finish
const run = await client.actor("novi/tiktok-user-search").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": [
"cat",
"lover",
],
"maxItems": 20,
"followerRange": "DEFAULT",
"profileType": "DEFAULT",
"searchField": "DEFAULT",
"location": "US",
"customMapFunction": "(object) => { return {...object} }",
}
# Run the Actor and wait for it to finish
run = client.actor("novi/tiktok-user-search").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": [
"cat",
"lover"
],
"maxItems": 20,
"followerRange": "DEFAULT",
"profileType": "DEFAULT",
"searchField": "DEFAULT",
"location": "US",
"customMapFunction": "(object) => { return {...object} }"
}' |
apify call novi/tiktok-user-search --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=novi/tiktok-user-search",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
Download the OpenAPI definition: https://api.apify.com/v2/actors/DCFT5wREK7BW3IJGc/builds/Qc41OGCQoL9jedwv3/openapi.json