# TikTok Profile Mention Scraper — Who @Tagged This Creator (`khadinakbar/tiktok-profile-mention-scraper`) Actor

Find public TikTok videos that @mention a profile. Paste usernames or profile URLs; get video URL, caption, author, engagement, and ID-verified match evidence. Cookieless ScrapeCreators + SociaVault. Not the profile's own posts. MCP-ready. $0.008/mention.

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

## Pricing

from $8.00 / 1,000 mention founds

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TikTok Profile Mention Scraper

Find public TikTok videos that **@mention** a creator or brand profile — not the profile's own posts. Paste usernames or profile URLs; each dataset row includes the video URL, caption, author, engagement, and whether TikTok's structured caption data confirms the exact account ID.

TikTok is a trademark of its owner. This independent Actor is not affiliated with, associated with, or endorsed by TikTok.

### Best fit for this Actor

- Brand monitoring for videos that tag your TikTok account
- Influencer deliverable checks before paying a creator
- UGC sourcing and campaign mention tallies
- Competitor watching — who is tagging a rival brand

When you already have the target handles and need **their own posts** next, continue with [TikTok Profile Posts Scraper](https://apify.com/khadinakbar/tiktok-profile-posts-scraper). When a mention video URL is known and you need **comment threads**, continue with [TikTok Video Comments Scraper](https://apify.com/khadinakbar/tiktok-video-comments-scraper). For the same job on Instagram photo-tags, continue with [Instagram Tagged Posts Scraper](https://apify.com/khadinakbar/instagram-tagged-posts-scraper).

### Practical scenario

A brand social team pastes `gymshark` with `maxResultsPerProfile: 3` and `onlyVerifiedMentions: true`. The Actor resolves the account ID, searches public TikTok keyword results for `@gymshark`, keeps only posts whose caption entities link that ID (and skips Gymshark's own videos), then writes three billed mention rows with author handles and like/play counts for sponsorship review.

### Quick start input

```json
{
  "usernames": ["gymshark"],
  "maxResultsPerProfile": 3,
  "onlyVerifiedMentions": true
}
```

### Input reference

| Field | Type | What it controls |
|---|---|---|
| `usernames` | array | Required handles or profile URLs. Example: `gymshark`. |
| `maxResultsPerProfile` | integer | Cap per profile (1–200). Prefill 3 for quality tests. |
| `maxSearchPages` | integer | Keyword-search pagination safety limit (default 5). |
| `onlyVerifiedMentions` | boolean | Default true — only ID-confirmed tags. Set false to also keep caption-text `@handle` hits. |
| `onlyVideosNewerThan` | string | Optional `YYYY-MM-DD` or `7 days` / `2 months`. |
| `includeAuthorStats` | boolean | Include author follower/following when available. |
| `providerOrder` | enum | Diagnostic provider pin; default `scrapecreators-first`. |

### What data you receive

One dataset item is one public mention video.

```json
{
  "videoId": "7545933721589910798",
  "videoUrl": "https://www.tiktok.com/@fitcreator/video/7545933721589910798",
  "caption": "New drop with @gymshark code SAVE10",
  "authorUsername": "fitcreator",
  "diggCount": 12500,
  "playCount": 250000,
  "matchType": "verified",
  "isVerifiedMention": true,
  "inputUsername": "gymshark",
  "provider": "scrapecreators",
  "scrapedAt": "2026-09-21T12:00:00.000Z"
}
```

| Field | Meaning |
|---|---|
| `matchType` | `verified` = TikTok `text_extra` user ID match; `caption_text` = caption `@handle` only |
| `isVerifiedMention` | True when the structured caption entity links the target account |
| `authorUsername` | Who posted the mention (never the target when filters work) |
| `provider` | `scrapecreators`, `sociavault`, or `google` |

`OUTPUT` and `RUN_SUMMARY` in the default key-value store hold `outcome`, `itemsPushed`, and cost estimates.

### Coverage contract

- Discovery uses public keyword search (and optional Google) for indexed videos that tag a handle.
- Default mode bills **ID-verified** mentions. Set `onlyVerifiedMentions: false` when you also want caption-text `@handle` hits.
- The target's own videos are filtered out of results.
- Known public handle with zero matching public mentions → `VALID_EMPTY` (unbilled).
- Empty / reserved / non-TikTok input → `INVALID_INPUT`.
- Total provider outage with zero rows → `UPSTREAM_FAILED`.

### Pricing

Pay per event + platform usage pass-through:

- `apify-actor-start`: $0.00005
- `mention-found`: $0.008 per saved mention video

Invalid input and fully empty verified searches are not charged the mention event. See the Actor Pricing tab for the live table.

### How to use

1. Open the Actor in Apify Console and paste one or more TikTok handles.
2. Keep `onlyVerifiedMentions: true` for sponsorship-grade matches.
3. Run, then export the dataset as JSON/CSV or read it from the API/MCP.

#### API example

```bash
curl "https://api.apify.com/v2/acts/khadinakbar~tiktok-profile-mention-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["gymshark"],"maxResultsPerProfile":3,"onlyVerifiedMentions":true}'
```

#### Agent prompt card

> Use `khadinakbar/tiktok-profile-mention-scraper` with `usernames: ["brand"]`, `maxResultsPerProfile: 5`, `onlyVerifiedMentions: true`. Read dataset rows for `videoUrl`, `authorUsername`, `matchType`, and `isVerifiedMention`. Check `RUN_SUMMARY.outcome` before trusting empty results.

### Best results tips

- Prefer brand/creator handles that get tagged often (`gymshark`, major retailers).
- Raise `maxSearchPages` only when a first page returns few verified hits.
- Pair mention discovery with [TikTok Profile Scraper](https://apify.com/khadinakbar/tiktok-profile-scraper) when you need the target's follower counts.

### Builder's note

While wiring this Actor we live-probed ScrapeCreators `GET /v1/tiktok/search/keyword` with `trim=false` and confirmed `text_extra` type-0 rows carry the exact `user_id` of the tagged account (for example Gymshark’s resolved ID). That is why default billing requires ID verification instead of billing every caption that merely contains the word “gymshark”. With `trim=true` those entities disappear — keep trim off in production.

### Legal / responsible use

Use only for public data and lawful brand-safety, marketing, or research workflows. Respect TikTok's terms and applicable privacy laws. Do not use this Actor to harass people or scrape private content.

### Support

Open an Issue on the Actor page with the run ID and input (no secrets). After mention discovery, continue to [TikTok Profile Posts Scraper](https://apify.com/khadinakbar/tiktok-profile-posts-scraper) for the target’s own grid, [TikTok Video Comments Scraper](https://apify.com/khadinakbar/tiktok-video-comments-scraper) for commenters on a found video, or [Instagram Tagged Posts Scraper](https://apify.com/khadinakbar/instagram-tagged-posts-scraper) for the same UGC job on Instagram.

# Changelog

This Actor's version history is a separate document: https://apify.com/khadinakbar/tiktok-profile-mention-scraper/changelog.md

# Actor input Schema

## `usernames` (type: `array`):

TikTok profiles to find @mentions of. Accepts plain handles (e.g. "gymshark"), @handles, or full profile URLs (e.g. "https://www.tiktok.com/@gymshark"). Returns videos where others tagged this profile — not the profile's own posts. NOT a video URL, hashtag, or music URL.

## `maxResultsPerProfile` (type: `integer`):

Upper bound on mention videos saved per username. Accepts 1-200; defaults to 20. Quality tests should use 3. NOT a global run cap across all profiles.

## `maxSearchPages` (type: `integer`):

Safety limit on TikTok keyword-search pagination depth per profile. Rarely-tagged accounts can return pages with no real mentions — this stops the run rather than searching indefinitely. Default 5, max 30.

## `onlyVerifiedMentions` (type: `boolean`):

On (recommended): return only posts where TikTok's caption text_extra links the exact account ID. Off: also keep caption-text @handle hits labelled caption_text — useful for wider brand monitoring, but not proof the account was tagged.

## `onlyVideosNewerThan` (type: `string`):

Optional date filter. Accepts YYYY-MM-DD or relative windows such as "7 days" or "2 months". Videos older than this timestamp are skipped. Leave empty to keep every matching mention within maxResultsPerProfile.

## `includeAuthorStats` (type: `boolean`):

When true, each row may include the posting author's follower and following counts when the provider exposes them. Defaults to true for sponsorship / UGC scoring.

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

Which upstream data provider to try first. Default scrapecreators-first. Use sociavault-first or vendor-only pins for diagnostics — not required for normal runs.

## Actor input object example

```json
{
  "usernames": [
    "gymshark",
    "https://www.tiktok.com/@nike"
  ],
  "maxResultsPerProfile": 3,
  "maxSearchPages": 5,
  "onlyVerifiedMentions": true,
  "includeAuthorStats": true,
  "providerOrder": "scrapecreators-first"
}
```

# Actor output Schema

## `mentions` (type: `string`):

One row per public TikTok video that @mentions the target profile.

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

Terminal outcome, row counts, and spend estimate.

## `output` (type: `string`):

Same summary under the OUTPUT key for agent readback.

# 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 = {
    "usernames": [
        "gymshark"
    ],
    "maxResultsPerProfile": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/tiktok-profile-mention-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 = {
    "usernames": ["gymshark"],
    "maxResultsPerProfile": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/tiktok-profile-mention-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 '{
  "usernames": [
    "gymshark"
  ],
  "maxResultsPerProfile": 3
}' |
apify call khadinakbar/tiktok-profile-mention-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/tiktok-profile-mention-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/PZkHgmDNacbcQI7uv/builds/TLsexceOgeDrwpG65/openapi.json