Use TikTok Verified Mention Tracker with Python

Find TikTok posts that tag a specific creator or brand handle, with each result checked against TikTok's own mention markup so you can tell a real @mention from a caption that merely contains the name.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "addPostCountry": false,
  "downloadVideos": false,
  "excludeOwnPosts": true,
  "followRelatedVideos": false,
  "maxResultsPerProfile": 3,
  "searchDepth": "standard",
  "usernames": [
    "billieeilish"
  ]
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`usernames`	array	required	Brand or creator accounts whose mentions you want. Type a handle (nike), a handle with @ (@nike) or paste a profile link (https://www.tiktok.com/@nike). One account per line; duplicates are merged.
`mentionFilter`	string	optional	Every saved post carries a mentionType label: 'tagged' (the caption contains TikTok's clickable tag of the account), 'captionText' (the caption types @handle without a working tag) or 'searchResult' (TikTok search returned it for the handle, but the caption doesn't name the account). By default you get real mentions: tagged posts plus @handle captions.
`excludeOwnPosts`	boolean	optional	Leave out posts published by the tracked account itself, so you only see what other people say about it.
`datePosted`	string	optional	Only look at posts published in this period.
`postedAfter`	string	optional	Exact cut-off date. Use a date (2026-10-01) or a relative age such as '3 days' or '2 weeks'. Works together with 'Posted within'; the stricter of the two applies.
`sortBy`	string	optional	How saved posts are ordered for each account. 'Most liked' and 'Newest first' look at every post found before keeping the top ones.
`minPlayCount`	integer	optional	Skip posts with fewer views than this. Leave empty to keep posts of any size.
`searchDepth`	string	optional	'Standard' runs one search per account and reads every page TikTok returns. 'Deep' adds searches by plain handle, display name and #handle, a most-liked pass, several date ranges and the Photo tab, then merges them without duplicates. Deep finds noticeably more mentions but takes a few minutes per account. Set the run memory to at least 2048 MB for deep search.
`searchCountry`	string	optional	TikTok shows different posts in different countries. Pick a country to see the mentions people there get in their search results (for example Japan for Japanese posts). 'Any' uses the fastest connection. Runs with a country are slower.
`followRelatedVideos`	boolean	optional	After searching, open TikTok's related videos for every post that tags the account and keep related posts that also mention it (repeating a few hops). Often finds many extra tagged posts, mostly from creators who tag the account regularly. Slower, and needs at least 4096 MB of run memory.
`maxResultsPerProfile`	integer	optional	Stop after this many saved posts for each account. TikTok search usually yields tens to a few hundred posts per account, so very high values simply mean 'everything found'.
`maxItems`	integer	optional	Optional limit across all accounts in this run. Leave empty for no overall limit.
`downloadVideos`	boolean	optional	Download each saved video into this run's key-value store and add a permanent link to it (downloadedVideoUrl). TikTok's own video links only play inside TikTok, so turn this on when you need playable files. It makes runs slower and uses storage.
`addPostCountry`	boolean	optional	Look up the country TikTok records for every saved post (locationCreated, e.g. US, BR, JP). Useful for market breakdowns of who mentions you. Adds a few seconds per post.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/DEEd7YgSb54ZumfKB/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

TikTok posts that tag or @mention the tracked accounts: mention type, matching tag, caption, post date, views, likes, comments, shares, author profile, sound, video or slideshow details.

Questions before you run

Which inputs are required?

The published required fields are usernames

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build XPPVccGgUqsYp0fEv and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.