Tiktok Search Scraper avatar

Tiktok Search Scraper

Pricing

from $99.00 / 1,000 video results

Go to Apify Store
Tiktok Search Scraper

Tiktok Search Scraper

Fast, stealthy TikTok Search Scraper for real-time video data extraction. Get captions, views, music, and author details for any query. Features advanced anti-block technology. Perfectly optimized for marketing research, trend tracking, and influencer analytics on the Apify platform.

Pricing

from $99.00 / 1,000 video results

Rating

5.0

(1)

Developer

Emmanuel Uchenna

Emmanuel Uchenna

Maintained by Community

Actor stats

2

Bookmarked

46

Total users

1

Monthly active users

a month ago

Last modified

Features

Limited permissionsSingle-tenantServer interface

Share

Extract TikTok search video metadata with an Apify Actor built on the Apify SDK and Playwright. Search one or more terms, collect up to a limit per query, and export the results from the run's dataset.

The scraper combines API response interception, rehydration data, and DOM extraction. It supports residential or custom proxies, optional browser cookies, connection checks, and per-query failure reporting. TikTok can still restrict a session or require login; a working proxy alone does not guarantee results.

Documentation updated: October 17, 2026.

Quick start on Apify

  1. Open the Actor's Input tab.
  2. Add your search queries and set Max Items.
  3. Select Residential in Proxy configuration, or supply your own reachable proxy.
  4. Start the run and watch the logs.
  5. Review the run status and RUN_SUMMARY, then export the dataset.

Use this JSON for a small cloud run:

{
"queries": ["AI coding", "tech review"],
"maxItems": 5,
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": ["RESIDENTIAL"]
}
}

The limit is per query: this input can collect up to ten results. Fewer results are possible because of available content, scrolling limits, or restrictions. Video IDs are deduplicated within each query; the same video can appear again for another query. Dataset records do not include a query field, so use one query per run when exact query attribution is required.

When you maintain your own deployment, build the updated source before running it. Restarting an older build does not apply source changes.

Input reference

FieldTypeDefaultBehavior
queriesArray of non-empty stringsRequired in the input formSearch terms processed sequentially.
maxItemsInteger5Maximum results per query; allowed range 1–10000.
proxyConfigurationObjectResidential in the input schema and when omitted on ApifyConfigure Apify Proxy or a list of custom proxyUrls. Explicit useApifyProxy: false disables Apify Proxy when no custom URLs are supplied.
sessionCookiesString containing a JSON cookie arrayUnsetOptional cookies exported from your own TikTok session.
customProxyUrlStringUnsetA single custom browser proxy; takes priority over proxyConfiguration.

Always supply queries explicitly. Invalid query arrays, limits, or custom proxy URLs fail input validation before browser code and the fingerprint model are loaded.

Proxy selection and account access

Proxy selection follows this order:

  1. A supplied customProxyUrl.
  2. Your proxyConfiguration, including its custom URL list or Apify Proxy settings.
  3. The residential default when configuration is omitted on Apify.

To use a direct connection, including your local IP during development, set:

{
"queries": ["AI coding"],
"maxItems": 5,
"proxyConfiguration": {
"useApifyProxy": false
}
}

Set this explicitly for local runs: SDK input-schema defaults can otherwise enable the residential configuration.

Apify's free plan includes proxy use within the platform, subject to usage credits and account limits. External proxy connections require a paid plan. The SDK uses the Actor's internal connection settings; manually supplying an external Apify proxy URL can have different access requirements even from a cloud run. Check proxy connection settings and current plan limits.

Each SDK-configured proxy session is reused for the connection check, warm-up, and search. A retry creates a new session ID. A single customProxyUrl remains the same on retries; any exit-IP rotation then depends on your proxy provider.

Custom proxies

Supported URL formats:

http://username:encoded-password@proxy.example:8080
https://username:encoded-password@proxy.example:8443
socks5://proxy.example:1080

These are placeholders. Replace the host, port, and credentials with your provider's values.

HTTP and HTTPS proxies support username/password authentication. URL-encode special characters in credentials. Chromium does not support authenticated SOCKS5 in this setup; use an HTTP/HTTPS endpoint or an unauthenticated SOCKS5 endpoint.

The proxy must be reachable from the Actor and support the required HTTPS traffic. On Apify, localhost refers to the container. A proxy on your own computer requires a reachable endpoint or tunnel, and both must stay online. Browser traffic uses that proxy; SDK storage and billing calls are separate.

Invalid custom proxy settings stop the run instead of silently falling back to a direct connection.

Optional session cookies

Under Advanced — Sessions and Custom Proxies, paste the JSON cookie array exported from your own TikTok browser session, for example with Cookie-Editor. The form accepts it as a string. Cookies are credentials: keep the export private.

The scraper normalizes common cookie-export fields and injects cookies before TikTok navigation. If recognized session cookies were successfully injected, it skips the TikTok homepage warm-up. Cookies can expire or be rejected after an IP change. They do not fix proxy authentication or change the exit IP.

After successful extraction, the Actor saves TikTok cookies as TIKTOK_SESSION_COOKIES in its default key-value store. At startup it loads that key as a fallback when no non-empty input cookie array was parsed. This only works while the store still contains the key: local reuse depends on SDK storage/purge settings, and separate cloud runs normally have different default stores. Cross-run reuse requires retaining the record in the same configured store or supplying the cookies again.

Output and data quality

Video records go to the run's default dataset. The Actor output's results link points to that dataset's items.

FieldMeaning and availability
id, urlVideo ID and link. Keep IDs as strings in downstream tools.
descriptionVideo caption when available.
viewsView count; API data may be numeric, while DOM values can be formatted strings such as 11K.
likes, comments, sharesEngagement counts when supplied by structured data. comments is a count, not comment text.
authoruniqueId, nickname, avatar, verified, and followers when available.
music, musicAuthorMusic metadata when available.
hashtagsAn array of extracted hashtag names.
durationSource-dependent value. API results usually provide a numeric duration; DOM extraction can return a displayed time or date tag.
timestampSource-dependent publication value, such as a Unix timestamp or a displayed relative time.
scrapedAtISO timestamp recording when the item was extracted.
sourceapi, rehydration, or dom.

Unavailable fields may be empty strings. The DOM fallback does not collect likes, comment counts, share counts, or follower counts. Inspect source and normalize counts and time values before analysis. A fallback record already collected for a video is not automatically enriched by a richer response arriving later.

Illustrative API-derived record; this is sample data, not a captured live result:

{
"id": "7580436439000000001",
"url": "https://www.tiktok.com/@demo_creator/video/7580436439000000001",
"description": "A coding workflow example #coding #ai",
"views": 1200,
"likes": 87,
"comments": 12,
"shares": 4,
"author": {
"uniqueId": "demo_creator",
"nickname": "Demo Creator",
"avatar": "",
"verified": false,
"followers": ""
},
"music": "Example sound",
"musicAuthor": "Demo Creator",
"hashtags": ["coding", "ai"],
"duration": 30,
"timestamp": 1767225600,
"scrapedAt": "2026-10-17T12:00:00.000Z",
"source": "api"
}

This Actor collects search-result metadata. It does not download video files or collect comment threads.

Run summary and failures

When execution reaches finalization, the default key-value store receives RUN_SUMMARY. For example:

{
"totalResults": 5,
"queries": [
{
"query": "AI coding",
"count": 5,
"error": null
}
],
"error": null,
"status": "succeeded"
}

status is succeeded or failed. A query that exhausts its attempts without extracted results makes the run fail with a nonzero exit code. The scraper cannot always distinguish a genuinely empty search from a restriction, so an empty exhausted query is treated as unconfirmed. Earlier dataset records remain available if a later query fails.

Invalid proxy configuration or rejected authentication stops the run immediately. Other failures can retry up to three attempts per query, with delays of approximately 8–11 seconds and 16–19 seconds before attempts two and three. Each attempt allows up to 35 scroll rounds and normally stops after four consecutive extraction rounds without new items. These are internal limits, not input fields.

A run that collects some results can succeed below maxItems. Inspect logs when completeness matters. Aborted or force-terminated runs may not write a final summary; the platform's run status is authoritative.

Troubleshooting cloud runs

Each proxied browser session first visits https://api.apify.com/v2/browser-info and expects HTTP 200 JSON containing a non-empty clientIp. The address is named clientIp, not ip (documented response).

A successful connection check logs:

[proxy-check] Browser connection and proxy authentication verified

Only then does the Actor warm up the session and navigate to TikTok.

Log or symptomMeaningWhat to check
ERR_INVALID_AUTH_CREDENTIALS or HTTP 407Proxy authentication/configuration failure before TikTok extraction.Credentials, selected proxy-group access, remaining usage, and internal versus external connection settings.
Proxy browser connection check did not return an IP address.Older builds expected the wrong ip response field and could reject a valid HTTP 200 response.Rebuild from the version that reads clientIp. This message alone does not establish a subscription problem.
HTTP 200 with a non-JSON body or no clientIpThe endpoint response did not match the expected schema.Endpoint availability, proxy response substitution, and the deployed build.
Proxy connection/tunnel errorThe browser could not complete its connection check.Proxy reachability, HTTPS support, and provider availability.
[detect] login, CAPTCHA, HTTP restriction, or no-content messages after the checkTikTok loaded or responded, but the session did not yield usable search content.The page diagnostics, exit IP/session, and optional cookie freshness.
Zero results after all attemptsNo query results could be confirmed.RUN_SUMMARY, the query itself, and page diagnostics; do not assume a successful empty scrape.

Local success and cloud success use different networks and may use different proxy/session state. Diagnose the first failing stage instead of assuming every failure is TikTok blocking.

Run from source

Use Node.js 22 to match the supplied Docker image.

git clone https://github.com/Eunit99/tiktokscraper.git
cd tiktokscraper
npm ci
npx playwright install chromium

Create storage/key_value_stores/default/INPUT.json in your editor, creating the directories if needed. Use the direct-connection JSON above for a local smoke run, or provide valid proxy settings.

$npm start

Local outputs use storage/datasets/default/ and storage/key_value_stores/default/ unless storage is configured differently. Keep local input and exported cookies out of version control.

The source uses a headed Chromium browser on Apify or when DISPLAY is set, and headless mode otherwise. Cloud runs therefore need a virtual display; check that the startup command includes xvfb-run as in the Apify run logs. The repository uses apify/actor-node-playwright-chrome:22-1.58.2 with Playwright 1.58.2. Keep those versions aligned.

On Linux with Xvfb installed, the explicit virtual-display command is:

$npm run start:xvfb

Checks

npm test
npm run test:browser
node check-playwright-version.mjs

npm test runs the regression suite, including the documented clientIp response and fatal authentication behavior. test:browser is a separate real-Chromium check against a local authenticated proxy and needs the browser installed. The previously observed Windows rejected-password/cleanup timeout remains a limitation of that full browser check; local regression results do not certify a live TikTok cloud run.

Source map

FileResponsibility
src/main.jsInput validation, browser/session lifecycle, query limits, dataset writes, charging, cookie storage, and summary.
src/proxy.jsURL parsing, sticky proxy selection, authentication classification, and browser connection checks.
src/tiktokAntiDetect.jsThree extraction methods, cookie normalization, request headers, restriction detection, and page diagnostics.
src/humanBehavior.jsWarm-up, scrolling, mouse movement, and interaction timing.
src/profiles.js, src/fingerprint.js, src/evasions.jsBrowser profile selection and fingerprint/evasion setup.
.actor/Actor metadata and input/output/dataset schemas.

Automate a cloud run

The Apify JavaScript client runs the hosted Actor from your application. This still performs the scrape on Apify; it does not run it on your local IP.

$npm install apify-client

Set APIFY_TOKEN in your environment. Save this as run-search.mjs and run node run-search.mjs. The client waits for completion, retrieves the summary, and paginates the dataset, including any partial results from a failed run.

import { ApifyClient } from 'apify-client';
if (!process.env.APIFY_TOKEN) throw new Error('Set APIFY_TOKEN first.');
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('eunit/tiktok-search-scraper').call({
queries: ['AI coding'],
maxItems: 5,
proxyConfiguration: {
useApifyProxy: true,
apifyProxyGroups: ['RESIDENTIAL'],
},
});
console.log('Run status:', run.status);
const summaryRecord = await client
.keyValueStore(run.defaultKeyValueStoreId)
.getRecord('RUN_SUMMARY');
console.dir(summaryRecord?.value ?? null, { depth: null });
const dataset = client.dataset(run.defaultDatasetId);
let offset = 0;
while (true) {
const { items } = await dataset.listItems({ offset, limit: 1000 });
if (items.length === 0) break;
for (const item of items) console.dir(item, { depth: null });
offset += items.length;
}
if (run.status !== 'SUCCEEDED') {
process.exitCode = 1;
console.error('Inspect the run log and summary; any partial records remain in the dataset.');
}

Costs

The implementation records a video-result charging event for each unique video collected within a query. Use the Actor's current Pricing tab for event prices and billing terms. Platform, proxy, and storage usage depend on the deployment and listed pricing model; the per-query limit is not a fixed total-cost guarantee.

Start with a small run and review usage before increasing limits. Exported data remains available subject to the storage and retention settings of your Apify account.

Feedback and article source

Report reproducible issues in the Actor's Issues tab. Include the build ID, non-sensitive input settings, the first relevant log error, and the extraction source when available. Remove proxy credentials and session cookies before sharing.

The repository's ARTICLE.md contains the companion guide. Its publishing copy is maintained with the blog post titled How to scrape TikTok search results: A complete guide for 2026.