# TikTok Search Scraper (`headlessagent/tiktok-search-scraper`) Actor

Search TikTok videos and users by keyword. Returns clean, structured results to the dataset.

- **URL**: https://apify.com/headlessagent/tiktok-search-scraper.md
- **Developed by:** [Headless Agent](https://apify.com/headlessagent) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.63 / 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.

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 Search Scraper

Search **TikTok videos and accounts** by keyword and get the results as a clean dataset — ready to download as JSON, CSV, or Excel, or to process further via API.

Just enter your keywords and the Actor will run the search, automatically walk through multiple result pages, and save every video/user it finds to the dataset. Searches run in the English (US) region.

### Features

- Multi-keyword search in a single run
- Automatic pagination (configurable pages per keyword)
- Total result cap to keep costs under control
- Bring-your-own browser cookies when TikTok requires a trusted session
- Apify Proxy support for anti-blocking needs
- Enriched video output: views, likes, comments, shares, music, hashtags, duration, cover, direct video play/download URLs
- Author info with avatar, bio, verified badge, and follower stats
- Suggested accounts from the search page included as user rows
- Raw mode: push full unmodified API items with every field (`rawResults`)

### How to use

1. Fill in **Search queries** with one or more keywords.
2. Set **Results per page** (1–20) and **Max pages** to fit your needs.
3. (Optional) set **Results limit** to cap the total number of results.
4. Click **Start**. Results appear in the **Output / Dataset** tab.

#### Input parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `searchQuery` | string | – | A single keyword (used when `searchQueries` is empty) |
| `searchQueries` | array of string | `["funny cats"]` | List of keywords, processed one by one |
| `resultsPerPage` | integer (1–20) | `12` | Results per API page |
| `maxPages` | integer (1–10) | `1` | Paginated pages fetched per query |
| `cursorStart` | integer | `0` | Initial cursor (`0` = from the beginning; reuse a cursor from a previous run to continue) |
| `resultsLimit` | integer | `50` | Total result cap across all queries (`0` = no cap besides maxPages) |
| `rawResults` | boolean | `false` | Push full raw API items with all fields instead of parsed rows |
| `cookiesJson` | string | – | Browser cookies (see Cookies section) |
| `proxyConfiguration` | object | `{ "useApifyProxy": false }` | Proxy settings |

### Example request

```json
{
  "searchQueries": ["funny cats", "latte art"],
  "resultsPerPage": 12,
  "maxPages": 2,
  "resultsLimit": 40,
  "proxyConfiguration": { "useApifyProxy": true }
}
```

Run via API:

```bash
curl -X POST "https://api.apify.com/v2/acts/<ACTOR_ID>/runs?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchQueries": ["funny cats"], "resultsPerPage": 12, "maxPages": 2}'
```

Run locally:

```bash
uv sync
apify run
```

### Example response

Each result is stored as one row in the dataset.

**Video:**

```json
{
  "type": "video",
  "searchQuery": "funny cats",
  "id": "7679154654202154253",
  "desc": "funny cat playing ball #catsoftiktok",
  "createTime": 1787942554,
  "author": "@catlover (Cat Lover)",
  "authorUniqueId": "catlover",
  "authorNickname": "Cat Lover",
  "authorAvatar": "https://p16-common-sign.tiktokcdn.com/avatar.jpeg",
  "authorSignature": "Daily cute cats",
  "authorVerified": false,
  "authorFollowerCount": 36800,
  "authorFollowingCount": 6,
  "authorVideoCount": 214,
  "authorHeartCount": 716300,
  "plays": 1200000,
  "likes": 85000,
  "comments": 1200,
  "shares": 300,
  "collects": 1500,
  "musicTitle": "original sound",
  "musicAuthor": "catlover",
  "hashtags": ["catsoftiktok"],
  "duration": 15,
  "cover": "https://p16-common-sign.tiktokcdn.com/cover.image",
  "videoPlayUrl": "https://v16-webapp-prime.tiktok.com/video/...",
  "videoDownloadUrl": "https://v16-webapp-prime.tiktok.com/video/...",
  "url": "https://www.tiktok.com/@catlover/video/7679154654202154253"
}
```

**User / account** (regular results and suggested accounts — suggestions carry `"source": "suggestion"`):

```json
{
  "type": "user",
  "searchQuery": "funny cats",
  "uniqueId": "catlover",
  "nickname": "Cat Lover",
  "signature": "Funny Cats | Funny Animals",
  "avatar": "https://p19-common-sign.tiktokcdn.com/avatar.webp",
  "followers": 50000,
  "userId": "123456789",
  "verified": false,
  "url": "https://www.tiktok.com/@catlover"
}
```

**Raw mode** (`"rawResults": true`): each dataset row wraps the full unmodified API entry so it passes platform validation:

```json
{
  "searchQuery": "funny cats",
  "apiType": 1,
  "raw": {
    "type": 1,
    "item": { "...every field: video with all bitrateInfo variants, full author, music with playUrl, authorStats, statsV2, textExtra..." }
  }
}
```

`apiType` mirrors the original numeric result type (1 = video, 2 = user, 4 = suggested-users card, whose entry carries `user_list`). Use raw mode when you need fields the parsed rows don't carry.

**Run summary** (stored in the `OUTPUT` key-value store record):

```json
{
  "totalPushed": 24,
  "queries": ["funny cats", "latte art"]
}
```

### Cookies

If results come back empty and the log says TikTok requires a trusted session, fill in `cookiesJson` with cookies from a browser logged in to TikTok. Accepted formats:

- Object: `{ "sessionid": "...", "ttwid": "..." }`
- Playwright cookie list: `[ { "name": "...", "value": "..." } ]`
- A JSON string of either format above

### Tips

- Start with `maxPages: 1` and a small `resultsLimit` when trying new keywords.
- To resume an interrupted search, use the `cursor` value from the previous run log as `cursorStart`.
- If you get blocked frequently, enable `proxyConfiguration` with Apify Proxy.
- Request estimate: total requests ≈ number of keywords × `maxPages`.

### FAQ

**Why are my results empty?**
TikTok sometimes restricts search from fresh sessions. Provide fresh `cookiesJson` or enable the proxy, then run again.

**Is a TikTok login required?**
No. Cookies are only needed when TikTok blocks anonymous sessions.

**Which export formats are available?**
All built-in Apify dataset formats: JSON, CSV, Excel, XML, and RSS.

# Actor input Schema

## `searchQuery` (type: `string`):

A single search keyword (used when searchQueries is empty)

## `searchQueries` (type: `array`):

List of keywords — the Actor processes them one by one

## `resultsPerPage` (type: `integer`):

Results per API page (max ~20)

## `maxPages` (type: `integer`):

Number of auto-paginated pages per query

## `cursorStart` (type: `integer`):

Initial pagination cursor (0 = from the beginning)

## `resultsLimit` (type: `integer`):

Total result cap across all queries (0 = no cap besides maxPages)

## `rawResults` (type: `boolean`):

Push full raw API items with all fields instead of parsed rows

## `cookiesJson` (type: `string`):

Fresh browser cookies (object / Playwright list / JSON string). Required when the API returns an empty body.

## `proxyConfiguration` (type: `object`):

Anti-bot proxy settings

## Actor input object example

```json
{
  "searchQuery": "funny cats",
  "searchQueries": [
    "funny cats"
  ],
  "resultsPerPage": 12,
  "maxPages": 1,
  "cursorStart": 0,
  "resultsLimit": 50,
  "rawResults": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Video & user search results (dataset items).

## `summary` (type: `string`):

Run summary: totalPushed + queries (key-value store OUTPUT).

# 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 = {
    "searchQuery": "funny cats"
};

// Run the Actor and wait for it to finish
const run = await client.actor("headlessagent/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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "searchQuery": "funny cats" }

# Run the Actor and wait for it to finish
run = client.actor("headlessagent/tiktok-search-scraper").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 '{
  "searchQuery": "funny cats"
}' |
apify call headlessagent/tiktok-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,headlessagent/tiktok-search-scraper"
        }
    }
}

```

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/9aLvuEIsLVPoU5eFJ/builds/1YKwggO7KAZwP4Qzc/openapi.json