TikTok Scraper Pro

Scrape TikTok videos from profiles, direct video URLs, searches, hashtags, and music pages with clearer diagnostics, simpler pricing, and a cleaner output schema than older all-in-one actors.

Why This Actor Exists

Many TikTok scrapers are broad but hard to reason about:

• pricing gets complicated fast
• filter features are sold as add-ons
• empty runs are hard to diagnose
• outputs vary by surface and need cleanup before they are useful

TikTok Scraper Pro is built to be easier to run in production:

• one normalized video schema across supported surfaces
• honest accessStatus diagnostics per target
• built-in date and popularity filters
• optional session cookies for degraded public pages
• one simple pay-per-event model for emitted videos
• no external media extractor dependency in the production image

Supported Surfaces

• TikTok usernames and profile URLs
• Direct TikTok video URLs
• TikTok search result pages
• TikTok hashtag pages
• TikTok music and sound pages

What Data Can I Extract With TikTok Scraper Pro?

Identity	Content	Media	Metrics	Context
Video URL	Description	Cover URL	Views	Source surface
Video ID	Hashtags	Dynamic cover URL	Likes	Source input
Author username	Mentions	Play URL	Comments	Access status
Author display name	Create time	Download URL when available	Shares	Extraction method
Author ID	Sound title	Width and height	Saves	Warnings
Author verified flag	Sound author	Duration		Optional profile snapshot

Input

Core fields

• startUrls: mix profile URLs, usernames, direct video URLs, hashtag URLs, search URLs, and music URLs
• searchQueries: convenience field for keyword searches
• hashtags: convenience field for hashtag runs
• musicUrls: convenience field for sounds and music pages
• maxItemsPerTarget: per-target video cap
• dateFrom, dateTo: built-in date filtering
• minViews, minLikes, minComments: built-in popularity filters
• extractionMode: fast, balanced, or full
• includeProfileDetails
• includeDownloadUrls
• sessionCookieHeader
• proxyConfiguration
• residentialProxyFallbackMode: defaults to off; empty profiles retry once on your configured connection. Opt into retry to use Apify Residential proxy in the US for that retry. Residential proxy traffic costs more.
• emptyRunPolicy: defaults to retry_then_fail
• debugMode

Example input

{
  "startUrls": [
    "nike",
    "https://www.tiktok.com/search?q=marketing",
    "https://www.tiktok.com/music/original-sound-6689804660171082501"
  ],
  "maxItemsPerTarget": 10,
  "dateFrom": "30 days",
  "minLikes": 100,
  "includeProfileDetails": true,
  "includeDownloadUrls": true,
  "extractionMode": "balanced",
  "residentialProxyFallbackMode": "off"
}

Profile recovery and proxy costs

Profiles first use your proxyConfiguration, or a direct connection when omitted. A public profile shell can load without any video API response. The actor reads video IDs from universal profile state and nested item lists or ItemModule structures, then fetches video details in parallel. A false 404 on a video page also tries TikTok's embed page. It next scrolls the browser video grid, captures item_list responses, tries visible video links, and finally uses username search with exact-author filtering. The browser stops once the requested number of items is available.

An empty profile gets one fresh-session retry on your configured connection by default (off), including in mixed runs where another target succeeded. If the profile is still empty after that retry, its warnings include residential_retry_available so you can choose to opt in. Known private profiles are not retried. Set residentialProxyFallbackMode to retry to use Apify Residential proxy in the US for the empty profile retry only. Successful first passes do not create a residential configuration. Other surfaces retain their fresh-session retry on the configured connection. Your configured proxy remains in use on the first pass. If residential configuration or URL allocation fails, a warning is recorded and the fresh-session retry continues without that fallback.

Residential bandwidth costs extra and requires access on your Apify account. Recovery uses at most one residential attempt per empty target, with no external paid extractor. Larger item limits and mixed inputs can use more bandwidth. Direct video and hashtag inputs do not automatically opt into residential proxy use.

A single profile has a 13-second stage budget on its initial connection and a 30-second stage budget on retry. Profile HTML gets up to 5 seconds. Video pages and embeds each get up to 4 seconds, with parallel detail recovery bounded at 8 seconds total. Grid collection uses the remaining stage budget, capped at 20 seconds. Search runs only when at least 4 seconds remain and gets up to 5 seconds, including navigation. Later stages receive only the remaining budget, so these caps do not add together. A slow grid can skip search or detail hydration.

Browser initialization, including Chromium launch, context setup, scripts, and cookies, has an 8-second bound for profile-only groups. Mixed and other groups receive an explicit initialization timeout capped by the remaining pass budget. Targets sharing a proxy configuration reuse one browser per pass. Residential profile retries use a separate proxy group. Proxy configuration and URL allocation each have a 1-second cap, with URL allocation also capped by the remaining pass budget.

Each initial or retry pass has a 45-second scrape deadline. Target stages receive only the time left, and a final timeout around each target protects completed results if a dependency stalls. When the deadline expires, completed videos are kept and unfinished targets are marked timed_out with pass_deadline_exceeded.

Browser cleanup has a 2-second allowance per client, including cleanup of resources arriving after initialization times out. Page cleanup has a 2-second allowance followed by a 250-millisecond grace period for pending work. Cleanup failures are logged and do not block delivery indefinitely; the actor process exits after finalization. These cleanup allowances can extend elapsed time beyond the scrape deadline.

Apify initialization, input retrieval, dataset writes, charging, and artifact persistence add service latency outside these budgets. Live wall-clock performance still needs verification.

Output

Each dataset item is one normalized TikTok video record.

{
  "recordType": "video",
  "sourceType": "search",
  "sourceInput": "https://www.tiktok.com/search?q=marketing",
  "canonicalUrl": "https://www.tiktok.com/@ceekmarketing/video/7608320917227179286",
  "id": "7608320917227179286",
  "description": "Save these content trends for your next content day...",
  "hashtags": ["socialmedia", "contenttrends", "marketing"],
  "mentions": [],
  "createTime": "2026-02-18T12:11:03.000Z",
  "durationSeconds": 48,
  "coverUrl": "https://...",
  "videoUrl": "https://...",
  "downloadUrl": "https://...",
  "commentCount": 12,
  "likeCount": 500,
  "shareCount": 20,
  "viewCount": 20000,
  "authorUsername": "ceekmarketing",
  "authorDisplayName": "Ceek Marketing",
  "musicTitle": "Original Sound",
  "accessStatus": "success",
  "extractionMethod": "browser_api",
  "warnings": [],
  "scrapedAt": "2026-03-26T13:30:00.000Z"
}

Diagnostics

This actor does not silently flatten blocked or degraded targets into fake success. Each target is summarized with:

• success
• partial_result
• empty_result
• login_wall
• rate_limited
• private_or_unavailable
• not_found
• unsupported_surface
• unknown_error
• timed_out: the scrape pass ran out of time; the target includes the pass_deadline_exceeded warning.

It also persists:

• RUN_META
• SUMMARY.json

Profile item and target warnings include stage diagnostics such as http_profile:403, universal_scope:no_item_list, browser_item_list:timeout, search_fallback:0, and universal_video_ids:5. Browser HTTP/API response statuses and video/embed outcomes are included when available. Timeout, empty, unavailable, and budget-skipped outcomes are distinct. A diagnostic in warnings can describe a successful stage as well as a failure.

RUN_META.warnings includes target diagnostics. RUN_META.targetAttempts preserves each attempt's target statuses, emitted counts, and warnings, so a successful retry does not erase the original failure. retryUsed and usedResidentialFallback distinguish a retry from an actually allocated residential proxy URL. SUMMARY.json contains the final target outcomes with warnings from both attempts.

API Examples

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('netdesignr/tiktok-scraper-pro').call({
  searchQueries: ['marketing'],
  maxItemsPerTarget: 5,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();

Python

from apify_client import ApifyClient
import os

client = ApifyClient(os.environ["APIFY_TOKEN"])

run = client.actor("netdesignr/tiktok-scraper-pro").call(run_input={
    "hashtags": ["travel"],
    "maxItemsPerTarget": 5,
})

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

cURL

curl -X POST "https://api.apify.com/v2/acts/netdesignr~tiktok-scraper-pro/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startUrls": ["https://www.tiktok.com/search?q=marketing"],
    "maxItemsPerTarget": 5
  }'

Positioning Against Older TikTok Actors

This actor is designed to compete on:

• simpler pricing
• stronger diagnostics
• cleaner schema
• built-in filtering instead of paid filter add-ons
• more honest handling of degraded public surfaces

Current Limitations

• TikTok profile, hashtag, and music collection can degrade on aggressive anti-bot conditions
• follower and following graph extraction is intentionally out of scope for v1
• full comment trees are out of scope for v1
• subtitles are not guaranteed across all surfaces yet

Responsible Use

Use this actor only for data you are permitted to access and process. Respect TikTok terms, local law, privacy obligations, and your downstream usage responsibilities.

Empty-run policy

emptyRunPolicy defaults to retry_then_fail. After the existing retry attempts, zero result items fail the run with a clear status message. Choose retry_then_warn to exit successfully with WARNING: 0 items when the actor has not hit a technical-failure condition. Original technical-failure conditions still force exit 1 regardless of this policy. Older saved retry_then_succeed inputs normalize to retry_then_warn. RUN_META retains actor telemetry and records itemsEmitted, requested, emptyRun, emptyRunPolicy, nonEmptySuccess, technicalSuccess, exitCode, and warnings. Summary-only output does not count as scraped results.