TikTok Posts Search Scraper

Apify actor that searches TikTok posts by keyword/hashtag and exports them as structured data. The default hashtag mode needs no TikTok login or cookies and works from any proxy country.

Features

• One keyword (query) or many (queries) — each searched separately, combined and de-duplicated by video.
• Hashtag mode (default) scrapes TikTok's public /tag/<keyword> feed, no login needed. Spaces are removed, so econet zimbabwe reads #econetzimbabwe. searchMode: "auto" from older saved inputs behaves the same way.
• TikTok pads rarely used hashtags with unrelated videos, so hashtag results keep only videos that carry the tag or mention every word of the keyword. Popular single-word tags such as #econet give the most results.
• Full-text search (searchMode: "search") is optional and requires TikTok login cookies.
• Auto-pagination by scrolling until numberOfPosts per keyword is reached.
• Actor-side timeSince/timeUntil date filtering (TikTok has no date operators).
• Anti-detection built in: stealth browser fingerprint, residential-proxy preflight, and automatic relaunch on a fresh IP when TikTok serves a captcha / empty responses.
• Results pushed per keyword, so an abort keeps everything collected so far.

Input

{
    "queries": ["econet", "#zimbabwe"],
    "numberOfPosts": 100,
    "searchMode": "hashtag",
    "region": "US",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US"
    }
}

numberOfPosts applies per keyword. Keep the RESIDENTIAL proxy — TikTok blocks datacenter IPs and serves empty/captcha responses to flagged exits.

Output

One dataset item per video. Fields are emitted in both clean and snake_case/camelCase forms so the item is a drop-in for the powerai/tiktok-hashtag-posts-scraper output that scraping-tool's normalizeSocialPost already understands.

{
    "id": "7401234567890123456",
    "url": "https://www.tiktok.com/@zimtech/video/7401234567890123456",
    "webVideoUrl": "https://www.tiktok.com/@zimtech/video/7401234567890123456",
    "text": "AI is changing Zim business #econet",
    "author": {
        "uniqueId": "zimtech", "unique_id": "zimtech",
        "nickname": "Zim Tech", "id": "99",
        "profileUrl": "https://www.tiktok.com/@zimtech", "verified": true
    },
    "create_time": 1782898212,
    "created_at": "2026-07-01T09:30:12.000Z",
    "likesCount": 4200,  "diggCount": 4200,   "digg_count": 4200,
    "commentsCount": 88, "commentCount": 88,  "comment_count": 88,
    "sharesCount": 12,   "shareCount": 12,    "share_count": 12,
    "viewsCount": 150000,"playCount": 150000, "play_count": 150000,
    "duration": 42,
    "hashtags": ["econet", "ai"],
    "searchQuery": "econet",
    "hashtag": "econet"
}

created_at is exact (TikTok exposes real upload timestamps, unlike YouTube search).

Integration (scraping-tool)

Drop-in for the existing TikTok keyword path — this is our own actor with the same output shape as powerai/tiktok-hashtag-posts-scraper, so set it as primary with the vendor as fallback (mirroring Facebook), and normalizeSocialPost needs no change:

// ACTOR_FALLBACKS in scrapingService.js
'outspoken_strategy/tiktok-post-search-scraper': 'powerai/tiktok-hashtag-posts-scraper',

// socialProjectMonitoringService.scrapeSocialPostsByKeyword (tiktok branch)
const res = await this.scrapingService.scrape({
    url: `https://www.tiktok.com/tag/${encodeURIComponent(keyword)}`,
    resultsLimit: requestCount,
    actor: 'outspoken_strategy/tiktok-post-search-scraper',
    timeout,
    additionalInput: {
        query: keyword, numberOfPosts: requestCount, region: 'ZW',
        proxyConfiguration: { useApifyProxy: true, apifyProxyGroups: ['RESIDENTIAL'], apifyProxyCountry: 'ZW' }
    },
    scrapeType: 'tiktok-keyword-search'
});

The existing normalizeSocialPost already reads author.unique_id, video_id/id, create_time, digg_count, comment_count, share_count, play_count — all present.

Local development

npm install
echo '{ "query": "artificial intelligence", "numberOfPosts": 30, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US" } }' > storage/key_value_stores/default/INPUT.json
npm start

Note: TikTok flags IPs that make many requests, so local runs from a home IP may be served empty responses — the actor is designed to run on Apify residential proxies. Deploy with apify push.

Search diagnostics

Confirmed empty searches finish successfully with zero results. Missing or invalid API responses remain failures after retries; they are not automatically attributed to flagged proxies. Each keyword gets its own retry budget. SEARCH_SUMMARY records outcomes and returned counts. DEBUG_SEARCH, DEBUG_HTML, and DEBUG_SCREENSHOT record the latest unsuccessful/empty attempt before its browser closes. Full-text results have hashtag: null; searchQuery retains the original phrase.

Full-text search mode only: when TikTok displays Log in to search, paste a JSON cookie array exported from your logged-in TikTok browser into the secret TikTok session cookies input. Use cookies with TikTok domains. Login walls stop immediately with an actionable error; proxy rotation cannot replace authentication. Expired sessions need renewal.

Environment variable cookies

Set the secret environment variable TIKTOK_COOKIES to the exported JSON cookie array, for example [{"name":"sessionid","value":"YOUR_SESSION_VALUE","domain":".tiktok.com","path":"/"}]. Paste the raw JSON array as the environment variable value (no wrapping quotes). The actor uses it when the cookies run input is omitted or empty. A nonempty cookies input overrides the environment variable; [] explicitly disables cookies.

Session diagnostics report the cookie source, counts, expiry and presence of session cookies before and after navigation. Cookie values and account identifiers are never included in these logs. A login wall distinguishes missing cookies from a session TikTok did not accept.

Bind the saved session to its country

Set TIKTOK_SESSION_COUNTRY to the country where the saved TIKTOK_COOKIES session was created, for example ZW. When using these environment cookies, this setting overrides the Apify proxy country in run input, including older saved inputs that still specify US. It does not override a custom proxy URL, disabled proxy, or cookies supplied directly through run input. Startup logs show the requested region and effective proxy country. Remove this setting or update it when replacing the saved session with one from another country.

TikTok rejects a session used from another country's IP and shows "Log in to search" instead of results. When the cookies include TikTok's store-country-code cookie, the actor uses that country for the Apify proxy automatically, for both environment and input cookies. It takes precedence over TIKTOK_SESSION_COUNTRY, and the log shows a warning when the two disagree.