# TikTok Video Search Scraper - Metrics & Filters (`khadinakbar/tiktok-video-search-scraper`) Actor

Search TikTok videos by keyword or hashtag and get views, likes, comments, shares, engagement rate, duration, hashtags and creator data. Filter by minimum views, likes, or duration. Cookieless, provider-backed, MCP-ready.

- **URL**: https://apify.com/khadinakbar/tiktok-video-search-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Social media, Automation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 tiktok video founds

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/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

## TikTok Video Search Scraper

Search **TikTok videos by keyword or hashtag** and get every metric that matters for content research, trend spotting, and competitor monitoring — views, likes, comments, shares, saves, a computed **engagement rate**, duration, hashtags, sound, and full creator data. Then narrow the haul with built-in **quality filters** (minimum views, likes, comments, shares, duration) so you only keep — and only pay for — the videos worth keeping.

No TikTok login, no cookies. Cookieless and provider-backed (ScrapeCreators primary, SociaVault fallback). MCP-ready for AI agents.

### What you get

One flat row per TikTok video, ready for spreadsheets, dashboards, or an LLM.

| Field | Description |
|---|---|
| `videoUrl` | Canonical tiktok.com link to the video |
| `caption` | Video caption / description |
| `authorUsername`, `authorNickname`, `authorVerified` | Creator handle, name, verified flag |
| `playCount`, `likeCount`, `commentCount`, `shareCount`, `collectCount` | Full engagement metrics |
| `engagementRate` | `(likes + comments + shares) / plays`, rounded to 4 decimals |
| `durationSeconds` | Video length in seconds |
| `hashtags` | Hashtags parsed from the caption |
| `musicTitle`, `musicAuthor`, `musicId` | Sound / music track |
| `coverUrl`, `imageUrls` | Thumbnail; image URLs for photo-carousel posts |
| `createdAt`, `scrapedAt` | ISO 8601 post time and scrape time |
| `region`, `provider`, `searchType`, `query` | Provenance and search context |

### When to use it

- **Content research** — find the best-performing videos for a topic before you film.
- **Trend & viral discovery** — set `minPlays` high and `sortBy: most-liked` to surface breakouts.
- **Competitor monitoring** — track videos ranking for a brand keyword or hashtag.
- **Influencer sourcing** — pull creators posting about your niche with real engagement numbers.
- **AI agents** — a clean keyword-in, structured-JSON-out tool over the Apify MCP server.

Need **user profiles, the "Top" tab, or general TikTok search** across multiple result types? Use the companion **TikTok Search Scraper**. Need **one video's full details** or a creator's whole feed? Use **TikTok Video Scraper**. This actor is focused on *searching videos by keyword or hashtag with metrics and filters*.

### Pricing

Pay-per-event, billed only for videos actually saved to the dataset:

- **Actor start** — $0.00005 per run.
- **TikTok video found** — from **$0.004** per saved video (volume-tiered down to $0.003).

Videos removed by your quality filters are **never charged**. A 50-video run costs about **$0.20**.

### Input

```json
{
  "searchQueries": ["nike running", "protein recipe"],
  "hashtags": ["running"],
  "maxResultsPerQuery": 50,
  "sortBy": "most-liked",
  "datePosted": "this-month",
  "region": "US",
  "minPlays": 100000,
  "minLikes": 5000,
  "maxDurationSeconds": 60,
  "includePhotoPosts": true
}
```

| Input | Description |
|---|---|
| `searchQueries` | **Required.** List of keywords to search. Each runs its own paginated video search. |
| `hashtags` | Optional list of hashtags (with or without `#`) to pull video feeds for. |
| `maxResultsPerQuery` | Max videos per query (1–10000, default 50). |
| `sortBy` | `relevance` (default), `most-liked`, or `date-posted`. Keyword searches only. |
| `datePosted` | Recency window for keyword searches. Default `all-time`. |
| `region` | Two-letter ISO country code. Default `US`. |
| `minPlays` / `minLikes` / `minComments` / `minShares` | Keep only videos at or above these thresholds. |
| `minDurationSeconds` / `maxDurationSeconds` | Keep only videos within this length range. |
| `includePhotoPosts` | Include TikTok image carousel posts (default `true`). |
| `providerOrder` | Backend provider routing. Default `scrapecreators-first`. |

### Output example

```json
{
  "searchType": "keyword",
  "query": "nike running",
  "provider": "scrapecreators",
  "videoId": "7412345678901234567",
  "videoUrl": "https://www.tiktok.com/@runner/video/7412345678901234567",
  "caption": "Best nike running shoes #running #nike",
  "authorUsername": "runner",
  "authorVerified": true,
  "playCount": 250000,
  "likeCount": 12000,
  "commentCount": 340,
  "shareCount": 210,
  "collectCount": 90,
  "engagementRate": 0.0502,
  "durationSeconds": 32,
  "hashtags": ["running", "nike"],
  "musicTitle": "Original sound",
  "createdAt": "2024-06-01T00:00:00.000Z",
  "scrapedAt": "2026-07-01T12:00:00.000Z"
}
```

### Use via API

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("khadinakbar/tiktok-video-search-scraper").call(run_input={
    "searchQueries": ["nike running"],
    "maxResultsPerQuery": 50,
    "sortBy": "most-liked",
    "minPlays": 100000,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["videoUrl"], item["playCount"], item["engagementRate"])
```

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

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });
const run = await client.actor('khadinakbar/tiktok-video-search-scraper').call({
    searchQueries: ['nike running'],
    maxResultsPerQuery: 50,
    sortBy: 'most-liked',
    minPlays: 100000,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Use with AI agents (MCP)

Exposed through the Apify MCP server as `khadinakbar/tiktok-video-search-scraper`. Agents pass a keyword and optional filters and get back structured video rows with engagement metrics — ideal for "find the top TikTok videos about X" tasks.

### FAQ

**Do I need a TikTok account or cookies?** No. This actor uses public data via managed providers.

**Why did a run return fewer rows than my cap?** Either TikTok had fewer matching videos, or your quality filters removed some. Filtered-out videos are logged in `RUN_SUMMARY.filteredOut` and are never charged.

**What does a zero-result run mean?** The keyword genuinely had no matches (or none passed your filters). The run still finishes successfully with a clear status message. If every provider request failed instead, the run fails honestly with the errors in `RUN_SUMMARY.providerErrors`.

**Can I search multiple keywords at once?** Yes. Each entry in `searchQueries` (and each hashtag) runs its own search up to `maxResultsPerQuery`.

**How is engagement rate calculated?** `(likes + comments + shares) / plays`, rounded to 4 decimals. It is null when the play count is unavailable.

### Legal

This actor collects only publicly available TikTok data. Use it in compliance with TikTok's Terms of Service, applicable data-protection laws (including GDPR and CCPA), and only for purposes you are authorized to pursue. You are responsible for how you use the collected data. It does not access private accounts, bypass authentication, or collect data behind a login.

# Actor input Schema

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

One or more keywords to search TikTok videos for, e.g. 'protein recipe' or 'nike running'. Each keyword runs its own paginated video search. Provide keywords here OR hashtags in the Hashtags field (at least one is needed). Plain text only — this is NOT a TikTok URL, username, or video link.

## `hashtags` (type: `array`):

Optional TikTok hashtags to pull the video feed for, with or without the leading '#', e.g. 'running' or '#fitness'. Each hashtag runs its own paginated video search alongside any keywords. Leave empty to search by keyword only.

## `maxResultsPerQuery` (type: `integer`):

Maximum videos to return and charge for per keyword or hashtag. Ranges 1–10000, defaults to 50. The actor paginates until it hits this cap or runs out of videos. Applies independently to each query.

## `sortBy` (type: `string`):

Ordering for keyword searches: 'relevance' (TikTok default), 'most-liked' (highest engagement first), or 'date-posted' (newest first). Defaults to 'relevance'. Ignored for hashtag feeds, which return TikTok's native hashtag order.

## `datePosted` (type: `string`):

Restrict keyword searches to videos posted within a recent window: yesterday, this week, this month, the last 3 or 6 months, or all time. Defaults to 'all-time'. Applies to keyword searches only.

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

Two-letter ISO country code used to localize results, e.g. 'US', 'GB', or 'DE'. Defaults to 'US'. Changes which regional results TikTok surfaces for the same keyword.

## `minPlays` (type: `integer`):

Only keep videos with at least this many plays/views, e.g. 100000 to surface viral content. Defaults to 0 (no filter). Applied after fetching, so filtered-out videos are never charged. Videos missing a play count are dropped when this is set.

## `minLikes` (type: `integer`):

Only keep videos with at least this many likes, e.g. 5000. Defaults to 0 (no filter). Applied after fetching; filtered-out videos are not charged.

## `minComments` (type: `integer`):

Only keep videos with at least this many comments, e.g. 500. Defaults to 0 (no filter). Applied after fetching; filtered-out videos are not charged.

## `minShares` (type: `integer`):

Only keep videos with at least this many shares, e.g. 200. Defaults to 0 (no filter). Applied after fetching; filtered-out videos are not charged.

## `minDurationSeconds` (type: `integer`):

Only keep videos at least this many seconds long, e.g. 15 to skip very short clips. Defaults to 0 (no filter). Videos missing a duration are dropped when this is set.

## `maxDurationSeconds` (type: `integer`):

Only keep videos no longer than this many seconds, e.g. 60 to focus on short-form. Defaults to 0 (no limit). Videos missing a duration are dropped when this is set.

## `includePhotoPosts` (type: `boolean`):

TikTok search returns image carousel posts alongside videos. Keep true to include them, or set false to keep video posts only. Defaults to true.

## `maxPagesPerQuery` (type: `integer`):

Safety cap on how many provider pages to fetch per query before stopping, even if the result cap is not reached. Ranges 1–500, defaults to 20. Raise it only for very large result caps on sparse queries.

## `providerOrder` (type: `string`):

Which backend data provider to use. 'scrapecreators-first' tries ScrapeCreators then SociaVault (default); the other options force or reverse the order. Both providers return public TikTok video data with no cookies required.

## `includeRawData` (type: `boolean`):

Attach the raw, unnormalized provider payload to each row under 'rawResult' for debugging. Defaults to false to keep rows compact and cheap for AI agents to read.

## Actor input object example

```json
{
  "searchQueries": [
    "protein recipe",
    "morning routine"
  ],
  "hashtags": [
    "fitness",
    "running"
  ],
  "maxResultsPerQuery": 50,
  "sortBy": "relevance",
  "datePosted": "all-time",
  "region": "US",
  "minPlays": 0,
  "minLikes": 0,
  "minComments": 0,
  "minShares": 0,
  "minDurationSeconds": 0,
  "maxDurationSeconds": 0,
  "includePhotoPosts": true,
  "maxPagesPerQuery": 20,
  "providerOrder": "scrapecreators-first",
  "includeRawData": false
}
```

# Actor output Schema

## `videos` (type: `string`):

Videos with engagement metrics, creator info, hashtags, and URLs.

## `runSummary` (type: `string`):

Run diagnostics, provider telemetry, and filter stats.

# 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 = {
    "searchQueries": [
        "nike running"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/tiktok-video-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 = { "searchQueries": ["nike running"] }

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/tiktok-video-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 '{
  "searchQueries": [
    "nike running"
  ]
}' |
apify call khadinakbar/tiktok-video-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=khadinakbar/tiktok-video-search-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/Ae4eBFQ17VZR3QfiA/builds/NGt7Y9Wxf0kHWIFbu/openapi.json