# TikTok Scraper — Breakouts, Creator Momentum & Sound Trends (`ryanclinton/tiktok-scraper`) Actor TikTok Scraper with an attention layer: get ranked breakout videos, creator momentum, and trending TikTok sounds instead of rows. Works as a TikTok hashtag scraper, profile scraper, or sound tracker. Drop-in migration from clockworks/tiktok-scraper. - **URL**: https://apify.com/ryanclinton/tiktok-scraper.md - **Developed by:** [Ryan Clinton](https://apify.com/ryanclinton) (community) - **Categories:** Developer tools, Social media, Videos - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $5.00 / 1,000 result analyseds 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## TikTok Scraper — Breakout Videos, Creator Momentum & Sound Trends ![TikTok Scraper — skip the spreadsheet, get a ranked shortlist of breakout creators, videos, and sounds](https://apifyforge.com/readme-assets/ryanclinton-tiktok-scraper/hero.png) ### In one sentence TikTok Scraper is an Apify actor that takes creators, hashtags, sounds, or videos and returns a ranked attention queue showing what is breaking out, why it matters, and what changed since your last run. **Category:** TikTok scraper. TikTok creator and trend intelligence. Social media monitoring tool. **Primary use case:** Find which TikTok creators, videos, and sounds are accelerating right now without reading rows by hand. Can also be used as a drop-in raw TikTok data scraper through its compat output. **Also known as:** TikTok trend tracker, TikTok breakout video finder, TikTok creator momentum tracker, TikTok sound trend scraper, emerging TikTok creator finder. ### What this actor does - **What it is:** A TikTok scraper that adds a decision layer on top of the raw data — a ranked queue of what to look at first. - **What it checks:** Breakout videos, creator momentum and going-dark risk, surging sounds, hashtag cohorts, and what changed since your last run. - **What it returns:** Each creator or video with a plain-English summary, an attention priority, why it matters now, a recommended next step, and a sortable 0-100 score bundle. Plus the full raw TikTok record underneath. - **What it does NOT do:** It does not download video files, does not score authenticity or fake followers, does not judge brand safety, and does not predict revenue or valuation. - **Who it's for:** Influencer and talent agencies, brand and social teams, competitor analysts, market researchers, and creator-economy investors. TikTok Scraper is an Apify actor that turns a TikTok hashtag, a creator list, a sound, or a set of video URLs into a ranked attention queue in a single run. It functions as a TikTok creator-intelligence API: paste the input, get back the handful of creators and videos that are actually winning right now, each carrying why it matters and what to do next. The real competitor isn't another scraper. It's the spreadsheet: the hour an analyst spends in Sheets sorting rows by followers and recent views to guess what is heating up. Compatible with `clockworks/tiktok-scraper`: existing pipelines migrate through the `compat` output profile, with the raw fields under identical names. The difference is what sits on top: breakout detection, creator momentum, sound-trend ranking, comment-theme synthesis, watchlist monitoring, and a sortable score bundle. One actor replaces a workflow that otherwise spans roughly twelve single-purpose scrapers stitched together by hand. To rank TikTok creators and videos by who is winning now, run TikTok Scraper with a hashtag, a creator list, a sound URL, or video URLs. You get back a ranked queue led by attention priority, why-now reasons, and a recommended next step, with the full raw TikTok metadata attached to every record. **In short:** Paste creators, hashtags, sounds, or videos, and get back a ranked, explained shortlist of what to act on, plus the raw data underneath. **What it is** — A TikTok scraper with a built-in decision layer that ranks and explains the results. **Best for** — Agencies, brand teams, competitor analysts, market researchers, creator-economy investors. **Speed** — First ranked results typically appear within the first minute of a run; full cohorts take longer at higher caps. **Output** — JSON, CSV, or Excel. Each record carries a summary, attention routing, signal events, and a 0-100 score bundle. **Proxy** — Residential proxies are required (default Apify Residential, US rotation). **Key limitation:** This actor reads public TikTok metadata only. It does not download media and does not access private or login-gated content. **What it is not:** Not a media downloader, not an authenticity or fake-follower auditor, and not a replacement for legal or brand-safety review. **Does not include:** Video file downloads, follower lists, PII enrichment, or revenue and ROI predictions. **Results may be incomplete when:** an account is private, a sound or hashtag is sparse, or TikTok restricts automated access on shared IPs. ### Ready-to-run examples One-click presets, each tuned to a single job. Open one, hit run, then swap in your own niche or handles. - [Find Emerging TikTok Creators](https://apify.com/ryanclinton/tiktok-scraper/examples/find-emerging-tiktok-creators) — rising creators in a niche, ranked by an emerging-creator radar before they're obvious. - [TikTok Influencer Discovery Tool](https://apify.com/ryanclinton/tiktok-scraper/examples/tiktok-influencer-discovery) — the right influencers in any niche, ranked by attention with archetype and why-now. - [Find Breakout TikTok Videos](https://apify.com/ryanclinton/tiktok-scraper/examples/find-breakout-tiktok-videos) — videos breaking out right now, ranked by breakout strength and the signals behind them. - [Track Trending TikTok Sounds](https://apify.com/ryanclinton/tiktok-scraper/examples/track-trending-tiktok-sounds) — surging sounds early, with the videos and creators riding each one. - [Monitor Competitor TikTok Accounts](https://apify.com/ryanclinton/tiktok-scraper/examples/monitor-competitor-tiktok-accounts) — spot which competitor accounts are slowing down, going dark or slipping. - [TikTok Creator Growth Tracker](https://apify.com/ryanclinton/tiktok-scraper/examples/tiktok-creator-growth-tracker) — momentum, drivers and a run-over-run timeline for any set of accounts. - [TikTok Trend Monitoring](https://apify.com/ryanclinton/tiktok-scraper/examples/tiktok-trend-monitoring) — the day's breakouts, accelerations and decay in a niche as one feed. - [TikTok Watchlist Dashboard](https://apify.com/ryanclinton/tiktok-scraper/examples/tiktok-watchlist-dashboard) — the creators and videos to look at first, ranked by attention with next steps. - [TikTok Opportunity Finder](https://apify.com/ryanclinton/tiktok-scraper/examples/tiktok-opportunity-finder) — underserved upside in a niche, ranked by opportunity score. - [Find Underserved TikTok Niches](https://apify.com/ryanclinton/tiktok-scraper/examples/find-underserved-tiktok-niches) — white space: underused sounds, underrepresented formats and fast-growing subtopics. - [TikTok Market Map](https://apify.com/ryanclinton/tiktok-scraper/examples/tiktok-market-map) — the niche mapped into leaders, challengers, emerging and cooling. - [TikTok Intelligence Feed](https://apify.com/ryanclinton/tiktok-scraper/examples/tiktok-intelligence-feed) — new breakouts, accelerations and decay as a feed for Slack, Zapier and AI agents. [See all ready-to-run examples →](https://apify.com/ryanclinton/tiktok-scraper/examples) ### The real competitor isn't another scraper. It's the spreadsheet. That spreadsheet is the hour an analyst spends sorting rows to guess what is heating up. Four surfaces here replace that hour, and no other TikTok actor ships them: - **Emerging Creator Radar** — find the creators in a niche before they are obvious, and before they are expensive. - **Opportunity Finder** — surface the underserved openings: high engagement, low supply, early on a rising trend. - **Intelligence Feed** — one ranked list of what changed since your last run: new breakouts, surging sounds, creators going dark. - **Market Map** — see the structure of a niche at a glance: who leads, who is challenging, who is cooling. **Designed for:** influencer and talent agencies, brand and social teams, competitor analysts, market researchers, and creator-economy investors. #### What you'll actually see Run `{ "mode": "hashtag", "hashtags": ["skincare"], "rankBy": "opportunity" }` and the top of the dataset reads like a shortlist, not a spreadsheet (illustrative example): ```text TOP OPPORTUNITIES UNDER #SKINCARE 1. @rising_creator priority: HIGH Why now: 4x this creator's normal views · early on a surging sound · engagement above the niche average Action: Review this week 2. @niche_brand priority: HIGH Why now: first breakout in 3 months · posting cadence doubled Action: Add to watchlist ```` Every row carries the reason and the next step, with the full raw TikTok record underneath. Clockworks gives you TikTok rows. This actor tells you what to look at first. ![500 raw TikTok rows versus a ranked shortlist of 5 creators to act on](https://apifyforge.com/readme-assets/ryanclinton-tiktok-scraper/before-after.png) ### Generic TikTok scraper vs TikTok Scraper Same raw data underneath, a decision layer on top: | Capability | Generic TikTok scraper | TikTok Scraper | |---|---|---| | Raw TikTok data (compat field set) | ✓ | ✓ | | Breakout-video detection | ✗ | ✓ | | Creator momentum + going-dark risk | ✗ | ✓ | | Sound-trend lifecycle + `soundVirality` rank | ✗ | ✓ | | Attention queue (what to look at first) | ✗ | ✓ | | Watchlist deltas (what changed since last run) | ✗ | ✓ | | Opportunity Finder + Emerging Creator Radar | ✗ | ✓ | | Market Map + Intelligence Feed | ✗ | ✓ | **Why agencies and brand teams use it:** the output is a shortlist they can act on this week (who is rising, which sound to ride, which competitor went quiet), not a CSV to sort by hand. Creator scouts and social teams read the attention queue; competitor-intelligence teams run a watchlist on a schedule. ![Generic TikTok scraper versus TikTok Scraper capability comparison](https://apifyforge.com/readme-assets/ryanclinton-tiktok-scraper/comparison.png) ### What you get from one call **Input:** `{ "mode": "hashtag", "hashtags": ["skincare"], "rankBy": "breakoutPotential" }` **Returns:** - A ranked attention queue: the creators and videos under #skincare that are accelerating fastest right now. - For each one: a summary line, an attention priority, why-now reasons, and a recommended next step. - A 0-100 score bundle (attention, breakout, momentum, sound leverage, engagement quality, cadence risk) for sorting and filtering. - Typed signal events (breakout, acceleration, sound surge, going-dark) with a fresh/active/fading status. - The full raw TikTok record under every entry, so downstream code keeps working unchanged. - A run summary with a one-line headline, a daily briefing, and rising-creator/sound/hashtag leaderboards. **Typical time to first result:** under a minute for the leading entries. **Typical time to integrate:** minutes — existing pipelines that read raw TikTok fields work unchanged through the compat output. ![TikTok Opportunity Finder and Creator Radar discovery products](https://apifyforge.com/readme-assets/ryanclinton-tiktok-scraper/discovery-cards.png) ### What makes this different - **An attention queue, not a row dump** — every run opens on what to look at first, with the reason and a recommended next step, instead of native TikTok order. - **Sound-trend and breakout detection** — catch the surging sound and the popping video before they are obvious. The `soundVirality` rank axis has no equivalent on other TikTok actors. - **Watchlist mode** — name a watchlist, schedule the run, and get back only what changed: new breakouts, surging sounds, creators going dark. No diffing CSVs. If you were building this yourself, you would need to scrape the substrate, compute per-creator baselines, detect breakouts and sound surges, rank by the right axis, store history across runs, and write the change-diff logic, for every mode. This actor ships that as one decision layer. It functions as a TikTok intelligence API, producing ranked, explained outputs useful for creator discovery, competitor monitoring, and trend research. ![TikTok watchlist: what changed since the last run](https://apifyforge.com/readme-assets/ryanclinton-tiktok-scraper/change-feed.png) ### Quick answers **What is it?** A TikTok scraper that returns a ranked, explained shortlist of creators and videos — what is breaking out, why, and what changed — instead of raw rows you sort yourself. **How do I find emerging TikTok creators?** Run hashtag mode on your niche with `rankBy: opportunity` or `breakoutPotential`. The actor returns small-to-mid creators that are rising early, ranked ahead of the already-obvious accounts. **What makes it different?** Every record carries an attention priority, why-now reasons, a recommended next step, and a 0-100 score bundle. It also detects surging sounds and remembers entities across runs so it can tell you what changed. **What data sources does it use?** Public TikTok pages only — the same public metadata a logged-out visitor sees. No login, no private accounts, no media downloads. **What does it return?** A ranked attention queue, typed signal events, a score bundle, optional comment-theme synthesis, watchlist deltas, and the full raw TikTok record under every entry. **Is it a drop-in for `clockworks/tiktok-scraper`?** Yes. The input shape matches, and `outputProfile: "compat"` returns the exact standard field set so existing downstream code reading `item.playCount` works unchanged. ### At a glance **Quick facts:** - **Input:** A hashtag, a creator list, a sound URL, or video URLs — pick one mode. - **Output:** Ranked entity records (creator or video) with attention routing, signal events, and a 0-100 score bundle. JSON, CSV, or Excel. - **Modes:** hashtag (default), profiles, sounds, videos, search (opt-in). - **Rank axes:** attention, opportunity, breakoutPotential, momentum, recency, engagement, soundVirality, relevance. - **Batch size:** Up to 50 hashtags, 200 profiles, 100 sounds, or 500 video URLs per run. - **Proxy:** Residential required (default Apify Residential, US). - **Watchlist:** Set a name to get back only what changed on the next run. **Input → Output:** - Input: A hashtag (or creators, a sound, video URLs). - Process: The actor reads the public TikTok data, ranks and explains the results, and remembers each entity for next time. - Output: A ranked attention queue plus the raw data, in JSON, CSV, or Excel. **Best fit:** Finding emerging creators in a niche, spotting trending sounds early, weekly competitor momentum tracking, hashtag and trend research, and breakout video discovery. **Not ideal for:** Downloading TikTok videos, follower-list export, or any authenticity, brand-safety, or valuation judgement. **Does not include:** Media files, subtitles, follower/following lists, PII enrichment, or revenue predictions. **Problems this solves:** - How to tell which TikTok creators in a niche are accelerating without sorting rows by hand. - How to spot a surging TikTok sound before it is obvious. - How to track a set of competitor accounts week over week without diffing CSVs. - How to find breakout TikTok videos under a hashtag instead of scrolling native order. **Data trust:** All fields are derived from public TikTok metadata the actor fetches in the run. Cohort percentiles return null when the cohort is too small to rank fairly, and history fields carry `firstSightFallback: true` on first sight rather than fabricating a timeline. **Common questions this actor answers:** - **Which creators under this hashtag are popping right now?** The Attention Queue and Breakouts views, ranked by breakout strength. - **Which sound is about to break?** The Sound Trends view, with each creator's position on the sound's curve. - **Who in my competitor set is slowing down?** The Cadence Risks and Competitor Decay views. - **What changed since last week?** Watchlist mode, which leads with a change briefing. ### What is a TikTok creator-intelligence tool? A TikTok creator-intelligence tool turns raw TikTok metadata into decisions: which creator is accelerating, which sound is surging, which account is going quiet. Basic TikTok scrapers stop at the rows and leave the interpretation to a human in a spreadsheet. TikTok Scraper ships that interpretation (ranking, breakout detection, momentum, and change tracking) as the default output, so the answer arrives with the data. #### What is a TikTok trend tracker? A TikTok trend tracker follows how a sound, hashtag, or format is moving (emerging, accelerating, peaking, or cooling) instead of reporting a static count. TikTok Scraper assigns each sound and hashtag a lifecycle stage and a position on its adoption curve, so you can ride a trend early rather than after it peaks. #### What is a TikTok competitor monitoring tool? A TikTok competitor monitoring tool watches a set of accounts over time and reports what changed: who accelerated, who slowed, who went dark. TikTok Scraper does this through watchlist mode, which remembers the set across runs and leads each run with a change briefing. #### What is a TikTok influencer discovery tool? A TikTok influencer discovery tool surfaces creators worth working with before they are obvious. TikTok Scraper ranks small-to-mid creators who are rising early through the Emerging Creator Radar, ahead of the already-expensive accounts. ### What data can you extract? Every entry pairs the full raw TikTok record with a decision layer on top. The raw substrate matches the standard TikTok-scraper field set field-for-field. | Data point | Source | Availability | Example | |---|---|---|---| | **Play / like / share / comment counts** | Public video metadata | Always | `playCount: 4214900` | | **Creator handle and follower count** | Public profile metadata | Always | `handle: "glowbarlondon"`, `fans: 184300` | | **Caption, hashtags, mentions** | Public video metadata | Always | `hashtags: ["skincare", "skinbarrier"]` | | **Sound / music metadata** | Public video metadata | Always | `musicName: "original sound"` | | **Attention priority + why now** | Decision layer | Signals profile | `attentionPriority: "high"` | | **Signal events (breakout, surge, going-dark)** | Decision layer | Signals profile | `type: "breakout_video"` | | **Score bundle (0-100)** | Decision layer | Signals profile | `attentionScore: 87` | | **Sound leverage / trend position** | Decision layer | Sound-bearing records | `soundLeverageScore: 74` | | **Comment themes + sentiment** | Decision layer | At 30+ comments/video | `themes: ["where to buy", "praise"]` | | **Watchlist deltas** | Decision layer | When watchlist active | `changeFlags: ["NEW_BREAKOUT"]` | | **Cohort percentiles** | Decision layer | Cohort of 10+ | `plays: 92` (percentile) | | **Run summary + leaderboards** | Decision layer | Once per run | `risingCreators`, `risingSounds` | ### Why use TikTok Scraper? Finding the three creators worth acting on this week is slow. The usual workflow is to run a profile or hashtag scraper, dump the rows into a spreadsheet, sort by followers and recent views, eyeball which ones "look like they are growing," then repeat the whole thing next week and diff the files by hand. That is an hour of an analyst's time per niche, and it misses the early signals — the surging sound, the creator who just went quiet — that do not show up in a static sort. TikTok Scraper does that interpretation in the run. It ranks the cohort by who is winning now, attaches the reason to every entry, detects breakouts and sound surges, and remembers each entity so the next run can report only what changed. The buyer compares the output against an analyst's hour, not against a row vendor's price. **Key difference:** Clockworks gives you TikTok rows. This actor tells you what to look at first. This is not a price war. The actor competes on the decision layer and on unifying a job that is otherwise split across roughly twelve separate scrapers, not on undercutting a raw-row price. The cheap single-data-type buyer is well served elsewhere; the intelligence buyer who wants the answer is the fit here. ### Platform capabilities - **Scheduling** — run a watchlist daily, weekly, or on any interval, and get back only what changed. - **API access** — trigger from Python, JavaScript, or any HTTP client. - **Residential proxy rotation** — required and built in, so the actor reaches public TikTok pages reliably. - **Monitoring** — Slack or email alerts when runs fail, through Apify integrations. - **Integrations** — Zapier, Make, Google Sheets, webhooks, and any tool that reads an Apify dataset. ### Features TikTok Scraper ships five input modes and a single decision layer that sits on top of every one of them. The layer ranks the cohort, explains each entry, detects time-decaying signal events, and remembers entities across runs. Everything below is deterministic and present in the output you can sort, filter, and export. **Ranking and attention** - **Attention queue** — every entity carries an `attention` block: priority (high/medium/low/none), why-now reasons, a recommended next step, and a respond-within window. It detects accelerating creators across the cohort and surfaces the ones to look at first. - **Reranking by axis** — `rankBy` reorders results by `attention`, `opportunity`, `breakoutPotential`, `momentum`, `recency`, `engagement`, `relevance`, or `soundVirality`. Each record shows its native TikTok rank, its reranked rank, and every axis value at once. - **Score bundle** — a sortable 0-100 set on every record: `attentionScore`, `breakoutScore`, `momentumScore`, `soundLeverageScore`, `engagementQualityScore`, `cadenceRiskScore`, with plain-English drivers in `scoreEvidence`. **Signals and trends** - **Signal events** — typed, time-decaying events including breakout video, creator acceleration and deceleration, sound adoption surge, hashtag surge, cadence collapse (going dark), audience expansion, format shift, and topic migration. Each carries a fresh/active/fading/expired status. - **Signal profiles** — each creator gets an archetype: emerging, breakout, stable-authority, viral-fragile, high-engagement-low-scale, decelerating, dormant, or unclassified, with evidence. - **Sound trends** — sound-bearing records carry a trend lifecycle (emerging/accelerating/peak/cooling) and a trend position showing how early the creator got onto the sound. - **Cohort comparison** — percentiles that rank a record against the run's cohort on plays, engagement, share rate, and freshness. **Monitoring and discovery** - **Watchlist mode** — set a name to track a creator set, hashtag, or sound across runs. The run leads with a change briefing, then returns per-entity deltas and change flags. - **Comment-theme synthesis** — opt in at 30+ comments per video to get themes (what viewers ask for, praise, question), audience-language signals, and sentiment. - **Discovery surfaces** — an Emerging Creator Radar, a White Space view of underserved sounds and formats, a Market Map of the cohort, an Opportunities view, and an Intelligence Feed of the run's events. - **Cross-run memory** — a historical store banks public metrics on every entity a run touches, so records carry `history` (trajectory plus days tracked), `communitySignals`, store-wide leaderboards (Rising Creators / Sounds / Hashtags / Most Improved across tracked entities), and `similarCreators`. These warm up with use and are labelled "across tracked entities," never "all of TikTok." - **Drop-in compat** — `outputProfile: "compat"` returns the exact standard TikTok-scraper field set, including the `errorCode` taxonomy, for migration and raw ingestion. ![TikTok Scraper features: attention queue, breakout detection, watchlist, cross-run memory](https://apifyforge.com/readme-assets/ryanclinton-tiktok-scraper/feature-callouts.png) ### Use cases for TikTok creator intelligence #### How to find emerging TikTok creators Use when you need to find rising creators in a niche before they are expensive. Run hashtag mode with `rankBy: opportunity` and read the Emerging Creator Radar. Used by talent and influencer agency teams to shortlist creators who are small-to-mid, early on surging sounds, and accelerating. Key outputs: `signalProfile`, `opportunityScore`, `radarRank`, `scoreEvidence`. #### How to find viral TikTok sounds Use when a brand or social team needs to ride a sound before it peaks. Run sounds mode or hashtag mode with `rankBy: soundVirality`. Key outputs: `trendLifecycle`, `trendPosition`, `soundLeverageScore`, `trendOriginator`. #### How to monitor TikTok competitors Use when you track a competitor set week over week. Run profiles mode with a `watchlistName` on a schedule. The run leads with a change briefing and flags who accelerated, who slowed, and who went dark. Key outputs: `watchlist`, `riskState`, `changeStory`, `scores`. #### How to find breakout TikTok videos Use when you need the videos popping under a hashtag, not native order. Run hashtag mode with `rankBy: breakoutPotential` and read the Breakouts view. Key outputs: `signalEvents`, `breakoutScore`, `whyThisMatters`, `cohort`. #### How to track TikTok trends and research a niche Use when quantifying a hashtag's trajectory or mapping a niche. Run hashtag mode and read the Market Map and White Space views. Key outputs: `marketMap`, `whiteSpace`, `cohort`, `risingHashtags`. #### Best for TikTok hashtag scraping Use when you need all the videos, creators, and signals under one or more hashtags in a single run. Hashtag mode collects up to 1,000 videos per tag, ranks them by breakout potential or sound virality, and returns cohort percentiles. Key outputs: `signalEvents`, `cohort`, `trendLifecycle`, raw `substrate` fields. #### Best for TikTok profile scraping Use when you need a creator set analysed in one run rather than one profile scraper per account. Profiles mode takes up to 200 handles, ranks each creator by momentum or attention, and optionally enrolls them in a watchlist for weekly diff tracking. Key outputs: `signalProfile`, `scores`, `watchlist`. ![TikTok Market Map: leaders, challengers, emerging, and cooling creators](https://apifyforge.com/readme-assets/ryanclinton-tiktok-scraper/market-map.png) ### When to use TikTok Scraper **Best for:** finding emerging creators across a niche of 50-1,000 videos, weekly or daily competitor monitoring on a creator set, sound-trend tracking, and breakout discovery under busy hashtags. **Not ideal for:** downloading TikTok video files (this actor is metadata-only by design), exporting follower/following lists, or any authenticity, brand-safety, or valuation scoring — none of those ship here. ### How to scrape TikTok with TikTok Scraper 1. **Choose a mode and enter your input** — for the default, pick hashtag mode and enter a tag such as `skincare`. Or paste creators, a sound URL, or video URLs for the other modes. 2. **Set how to rank** — `breakoutPotential` is the default for hashtags and surfaces what is popping. Switch to `opportunity` for emerging creators or `soundVirality` for sound trends. 3. **Run the actor** — click Start. The leading ranked results land within about a minute; larger cohorts take longer. 4. **Read or download results** — open the Attention Queue view in the console, or export JSON, CSV, or Excel from the Dataset tab. ### First run tips - **Start with the default** — `{ "mode": "hashtag", "hashtags": ["skincare"], "rankBy": "breakoutPotential" }` returns a ranked shortlist in one run and shows the actor's shape. - **Open the Attention Queue view first** — the dataset has many views; the default Attention Queue is the 5-second read. The full record set is always there for analysts. - **Set a watchlist name to unlock monitoring** — without it you get a one-shot ranking. With it, the next run returns only what changed. History warms up over time, so start it on day one. - **Comments are off by default** — set `commentsSamplePerVideo` to 30 or more to get comment-theme synthesis. Leave it at 0 for the fastest run. - **Search mode is opt-in** — leave it off and use hashtag, profiles, sounds, or videos. Search must be acknowledged explicitly (see Limitations). ### Input parameters | Parameter | Type | Required | Default | Description | |---|---|---|---|---| | `mode` | string | Yes | `hashtag` | One of `hashtag`, `profiles`, `sounds`, `videos`, `search`. | | `hashtags` | string\[] | For hashtag mode | `["skincare"]` | Hashtags with or without `#`. Up to 50. | | `rankBy` | string | No | `breakoutPotential` | Rank axis: `attention`, `opportunity`, `breakoutPotential`, `momentum`, `recency`, `engagement`, `soundVirality`, `relevance`. | | `profiles` | string\[] | For profiles mode | `[]` | TikTok handles with or without `@`. Up to 200. | | `sounds` | string\[] | For sounds mode | `[]` | TikTok sound/music URLs or IDs. Up to 100. | | `videos` | string\[] | For videos mode | `[]` | TikTok video URLs. Up to 500. | | `searchQuery` | string | For search mode | — | Free-text query. Requires `searchModeAcknowledged`. | | `searchModeAcknowledged` | boolean | For search mode | `false` | Must be `true` to run search mode. | | `commentsSamplePerVideo` | integer | No | `0` | Public comments per video. 30+ enables comment-theme synthesis. Max 500. | | `watchlistName` | string | No | — | Set a name to enable cross-run monitoring on any mode. | | `maxVideosPerHashtag` | integer | No | `100` | Cap on videos per hashtag. Max 1,000. | | `maxRecentVideosPerProfile` | integer | No | `50` | Cap on recent videos per creator. Max 500. | | `maxVideosPerSound` | integer | No | `100` | Cap on videos per sound. Max 1,000. | | `maxResults` | integer | No | `100` | Cap on search-mode results. Max 1,000. | | `outputProfile` | string | No | `signals` | `signals` (full decision layer), `compat` (standard field set), `minimal` (IDs + URLs). | | `taskPack` | string | No | `none` | Adds a curated, product-shaped summary record for a specific job. | | `changeWindowDays` | integer | No | — | Produce a "what changed" read for the queried entities over this many days. | | `proxyConfiguration` | object | No | Residential US | Residential proxies required. | #### Input examples - **Find emerging creators under a hashtag (the default first run):** ```json { "mode": "hashtag", "hashtags": ["skincare"], "rankBy": "breakoutPotential" } ``` - **Monitor a competitor set on a schedule:** ```json { "mode": "profiles", "profiles": ["@glowbarlondon", "@theordinary"], "watchlistName": "skincare-competitors", "rankBy": "momentum" } ``` - **Track a surging sound and who rode it earliest:** ```json { "mode": "sounds", "sounds": ["https://www.tiktok.com/music/original-sound-7300000000000000000"], "rankBy": "soundVirality" } ``` #### Input tips - **Start with defaults** — hashtag mode plus `breakoutPotential` covers most first runs. - **Batch in one run** — 50 profiles in one run is more efficient than 50 single-profile runs. - **Use compat for raw ingestion** — set `outputProfile: "compat"` when you only need the standard field set for an existing pipeline. ### Output example A trimmed signals-profile record (the default `outputProfile: "signals"`): ```json { "recordType": "entity", "entityType": "video", "entityId": "7361500000000000000", "handle": "glowbarlondon", "summary": "Largest play spike on this creator in 3 months.", "whyThisMatters": [ "Plays well above this creator's recent baseline.", "Uses a sound that is surging in platform-wide usage." ], "attention": { "attentionPriority": "high", "whyNow": ["Fresh breakout still inside its early-reach window."], "deprioritizationReasons": [], "recommendedAction": "Review this creator within 3 days", "respondWithinDays": 3 }, "signalProfile": { "label": "breakout", "signalProfileStrength": 0.81, "signalProfileVersion": "1.0", "signalProfileEvidence": ["Recent breakout video", "Audience expansion detected"] }, "scores": { "attentionScore": 87, "breakoutScore": 91, "momentumScore": 64, "soundLeverageScore": 74, "engagementQualityScore": 70, "cadenceRiskScore": 12 }, "scoreEvidence": [ "Recent video 3.4x this creator's median plays.", "Sound appears in multiple rising videos this run." ], "signalEvents": [ { "type": "breakout_video", "signalStrength": 0.88, "active": true, "firstDetectedAt": "2026-06-18T00:00:00Z", "peakAt": null, "daysSincePeak": null, "decayStatus": "fresh", "reason": "Single video popping well above this creator's baseline.", "evidence": { "sampleSize": 42 } } ], "cohort": { "cohortType": "hashtag", "cohortName": "skincare", "cohortSize": 100, "cohortStatus": "ok", "percentiles": { "plays": 96, "engagementRate": 88, "shareRate": 91, "freshness": 73 } }, "substrate": { "id": "7361500000000000000", "text": "the only 3 steps your skin barrier needs", "createTimeISO": "2026-06-17T14:22:00Z", "authorMeta": { "name": "glowbarlondon", "nickName": "Glow Bar London", "fans": 184300, "verified": false }, "musicMeta": { "musicName": "original sound", "musicId": "7300000000000000000" }, "webVideoUrl": "https://www.tiktok.com/@glowbarlondon/video/7361500000000000000", "diggCount": 312400, "shareCount": 41200, "playCount": 4214900, "commentCount": 5870, "hashtags": [{ "name": "skincare" }, { "name": "skinbarrier" }] } } ``` A compat record (`outputProfile: "compat"`) — the exact standard TikTok-scraper shape, no decision fields: ```json { "id": "7361500000000000000", "text": "the only 3 steps your skin barrier needs", "createTimeISO": "2026-06-17T14:22:00Z", "authorMeta": { "id": "6700000000000000000", "name": "glowbarlondon", "nickName": "Glow Bar London", "fans": 184300, "verified": false }, "musicMeta": { "musicName": "original sound", "musicId": "7300000000000000000" }, "webVideoUrl": "https://www.tiktok.com/@glowbarlondon/video/7361500000000000000", "diggCount": 312400, "shareCount": 41200, "playCount": 4214900, "collectCount": 28700, "commentCount": 5870, "hashtags": [{ "name": "skincare" }, { "name": "skinbarrier" }], "isSlideshow": false } ``` ![Sample TikTok Scraper output: attention priority, why now, score, and recommended action](https://apifyforge.com/readme-assets/ryanclinton-tiktok-scraper/output-table.png) ### Output fields | Field | Type | Description | |---|---|---| | `recordType` | string | `entity`, `event`, `intelligenceFeed`, `watchlistBriefing`, `taskPack`, `summary`, or `error`. | | `entityType` | string | `video` or `creator`. | | `entityId` | string | Stable TikTok ID — the cross-run dedup key. | | `handle` | string | Creator handle, normalised without `@`. | | `summary` | string | One-line plain-English read of the record. | | `whyThisMatters` | string\[] | Up to four lines on why this entry stands out. | | `attention.attentionPriority` | string | `high`, `medium`, `low`, or `none`. | | `attention.whyNow` | string\[] | Plain-English reasons to act now. | | `attention.recommendedAction` | string | A prioritisation instruction (Review, Watch, Track), never an in-platform action. | | `signalProfile.label` | string | Creator archetype with evidence. | | `scores` | object | 0-100 bundle: attention, breakout, momentum, sound leverage, engagement quality, cadence risk. | | `scoreEvidence` | string\[] | Plain-English drivers behind the scores. | | `signalEvents` | object\[] | Typed, time-decaying events with a fresh/active/fading status. | | `cohort` | object | Percentile rank within the run's cohort. Null when the cohort is too small. | | `trendLifecycle` | object | Sound/hashtag stage: emerging, accelerating, peak, cooling. | | `riskState` | string | Competitor-decay read: healthy, softening, losing-momentum, going-dark. | | `history` | object | Cross-run trajectory for a tracked entity: days tracked, trend state, peak, and a recent-metric sparkline. `firstSightFallback: true` on first sight, never a fabricated timeline. | | `communitySignals` | object | Cross-run aggregate from the tracked-entity store: how often the entity has been seen, first detection, and its velocity percentile across tracked entities. | | `similarCreators` | object\[] | Creators most like this one across everything the store has tracked, with the shared dimensions. Warms up as the store accumulates; empty until it has data. | | `commentSynthesis` | object | Themes, audience-language signals, and sentiment. Opt-in at 30+ comments. | | `watchlist` | object | What changed since last run, when a watchlist is active. | | `substrate` | object | The full raw TikTok record (the exact standard field set). | | `errorCode` | string | On error records: stable code (`NOT_FOUND`, `PROFILE_PRIVATE`, `BOT_PROTECTION`, and more). | ### Scrape TikTok using the API #### Python ```python from apify_client import ApifyClient client = ApifyClient("YOUR_API_TOKEN") run = client.actor("ryanclinton/tiktok-scraper").call(run_input={ "mode": "hashtag", "hashtags": ["skincare"], "rankBy": "breakoutPotential" }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): if item.get("recordType") == "entity": print(f"{item['handle']}: {item['attention']['attentionPriority']} — {item['summary']}") ``` #### JavaScript ```javascript import { ApifyClient } from "apify-client"; const client = new ApifyClient({ token: "YOUR_API_TOKEN" }); const run = await client.actor("ryanclinton/tiktok-scraper").call({ mode: "hashtag", hashtags: ["skincare"], rankBy: "breakoutPotential" }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); for (const item of items) { if (item.recordType === "entity") { console.log(`${item.handle}: ${item.attention.attentionPriority} — ${item.summary}`); } } ``` #### cURL ```bash curl -X POST "https://api.apify.com/v2/acts/ryanclinton~tiktok-scraper/runs?token=YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mode": "hashtag", "hashtags": ["skincare"], "rankBy": "breakoutPotential" }' curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_API_TOKEN&format=json" ``` ### How TikTok Scraper works 1. **Read public TikTok data** — over required residential proxies, with no login and no media files. The raw record matches the standard TikTok-scraper field set exactly, so the compat output is a true drop-in. 2. **Detect what is accelerating** — each creator and video is measured against its own recent baseline and the run's cohort to surface what is unusually strong right now. 3. **Rank by importance** — results are ordered by the axis you chose (attention, opportunity, breakout potential, momentum, sound virality), each with the reason attached. 4. **Track changes over time** — public metrics are remembered across runs, so the actor can report momentum and what changed. First sight is reported honestly with `firstSightFallback`, never invented. ![How TikTok Scraper works: from public TikTok data to attention queue and discovery products](https://apifyforge.com/readme-assets/ryanclinton-tiktok-scraper/intelligence-layers.png) ### Tips for best results 1. **Lead with the right rank axis.** `breakoutPotential` for what is popping, `opportunity` for emerging creators, `soundVirality` for sound trends, `momentum` for competitor tracking. 2. **Run watchlists on a schedule.** The change briefing and deltas are most useful as a recurring feed, and history sharpens with each run. 3. **Size the cohort for cohort stats.** Percentiles need a cohort of at least 10; raise `maxVideosPerHashtag` if you want fuller ranking. 4. **Enable comments only when you need themes.** Set `commentsSamplePerVideo` to 30+ for synthesis; leave it at 0 for speed. 5. **Use task packs for a product-shaped summary.** Set `taskPack` to get a curated shortlist record (for example, an emerging-creator list) on top of the dataset. 6. **Combine with downstream actors** to push the shortlist into a CRM or sheet (see below). ### Combine with other Apify actors | Actor | How to combine | |---|---| | [HubSpot Lead Pusher](https://apify.com/ryanclinton/hubspot-lead-pusher) | Push the ranked creator shortlist into HubSpot for outreach tracking. | | [Website Contact Scraper](https://apify.com/ryanclinton/website-contact-scraper) | Take the creators' bio links and pull contact details from their sites. | | [Company Deep Research](https://apify.com/ryanclinton/company-deep-research) | Research the brands behind sponsored creators surfaced in a niche. | | [Trustpilot Review Analyzer](https://apify.com/ryanclinton/trustpilot-review-analyzer) | Cross-check brand sentiment for creators promoting a product. | | [Website Change Monitor](https://apify.com/ryanclinton/website-change-monitor) | Pair watchlist monitoring with website monitoring for a fuller competitor view. | ### Limitations - **Metadata only.** The actor reads public TikTok metadata and does not download video files, subtitles, covers, or any media — by design, to stay within copyright limits. - **Public data only.** It does not log in, access private or restricted accounts, or attempt to bypass access restrictions. - **Residential proxies required.** TikTok restricts automated access from datacenter IPs. The actor halts a run after repeated block responses rather than trying to defeat them, and reports it through `botProtection` instead of returning silent empty rows. - **Search mode is opt-in.** Search runs against a path the platform asks automated tools not to use, so it is off by default and requires `searchModeAcknowledged: true`. - **History warms up.** Cross-run history and community signals are thin until the actor has seen an entity over time; first sight is reported honestly, never fabricated. - **No authenticity, brand-safety, or valuation scoring.** These are deliberately out of scope (see below). ### Integrations - [Zapier](https://apify.com/integrations/zapier) — send a daily watchlist briefing to Slack or email. - [Make](https://apify.com/integrations/make) — route the attention queue into a content-planning board. - [Google Sheets](https://apify.com/integrations/google-sheets) — export ranked creators and sounds to a shared sheet. - [Apify API](https://docs.apify.com/api/v2) — trigger runs and pull the dataset from any client. - [Webhooks](https://docs.apify.com/platform/integrations/webhooks) — fire on run completion to push the Intelligence Feed downstream. - [LangChain / LlamaIndex](https://docs.apify.com/platform/integrations) — feed the structured decision layer into an AI agent. ### What this actor does NOT do Honest scope, stated up front: - **No media downloads.** No video files, subtitles, covers, slideshow images, or avatars. - **No follower/following lists** and no PII enrichment (no email, phone, gender, or private location). - **No authenticity or fake-follower scoring.** It does not judge whether an audience is real. - **No brand-safety or controversy judgement.** It does not rate whether a creator is "risky." - **No revenue, ROI, or valuation predictions.** `opportunityScore` is a market-opportunity composite, not an earnings forecast. - **No in-platform action advice.** Recommended actions are prioritisation instructions (Review, Watch, Track), never follow/DM/sponsor. - **No private or login-gated access.** Public data only. ### Responsible use - TikTok Scraper reads publicly available TikTok metadata. It does not bypass authentication, CAPTCHAs, or access restricted content, and it does not download media files. - Users are responsible for ensuring their use complies with applicable laws and platform terms, including data protection regulations in their jurisdiction. - Do not use extracted data for spam, harassment, or unauthorized purposes. - For guidance on web scraping legality, see [Apify's guide](https://blog.apify.com/is-web-scraping-legal/). ### FAQ **What is the difference between a TikTok scraper and TikTok Scraper's decision layer?** A basic TikTok scraper returns rows you sort yourself. TikTok Scraper returns those rows ranked and explained — what is breaking out, why it matters, and what changed — so the answer arrives with the data. **How do I find emerging TikTok creators with this actor?** Run hashtag mode on your niche with `rankBy: opportunity` and read the Emerging Creator Radar view. It ranks small-to-mid creators who are rising early ahead of the obvious accounts. **How do I track trending TikTok sounds?** Run sounds mode, or hashtag mode with `rankBy: soundVirality`. Each record shows the sound's lifecycle stage and how early the creator got onto it. The `soundVirality` axis is specific to this actor. **How does watchlist mode work?** Set a `watchlistName` and reuse it on a schedule. After the first run, the actor returns only what changed — new breakouts, surging sounds, creators going dark — and leads with a change briefing. **What does this actor return that a raw scraper doesn't?** An attention priority and recommended next step per record, typed signal events, a 0-100 score bundle, cohort percentiles, optional comment themes, and cross-run change tracking. **Can I use this for competitor monitoring?** Yes. Run profiles mode with a watchlist on a schedule. The Cadence Risks and Competitor Decay views surface who is slowing down or going quiet. **Can I migrate from `clockworks/tiktok-scraper` without changing my code?** Yes. The input shape matches and `outputProfile: "compat"` returns the exact standard field set, including the error-code taxonomy. It is a practical drop-in alternative for buyers who also want the decision layer. **Does it download TikTok videos?** No. The actor is metadata-only by design. It reads public data but does not download media files. **What proxies do I need?** Residential proxies are required and built in (default Apify Residential, US). TikTok restricts automated access from datacenter IPs. **Why is search mode off by default?** Search runs against a path the platform asks automated tools not to use, so it is opt-in and requires explicit acknowledgement. The default modes — hashtag, profiles, sounds, videos — do not. **Does it judge whether a creator is authentic or brand-safe?** No. Authenticity, fake-follower, and brand-safety scoring are deliberately out of scope. The actor describes momentum and reach, not quality or risk judgements. **Is it legal to scrape TikTok with this actor?** It reads only public metadata and does not bypass authentication or download media. Whether your use is permitted depends on your jurisdiction and intended use, including data-protection and platform-terms considerations; consult legal counsel for your specific case. **The bottom line:** Clockworks gives you TikTok rows. This actor tells you what to look at first. ### Help us improve If you encounter issues, you can help us debug faster by enabling run sharing in your Apify account: 1. Go to [Account Settings > Privacy](https://console.apify.com/account/privacy) 2. Enable **Share runs with public Actor creators** This lets us see your run details when something goes wrong, so we can fix issues faster. Your data is only visible to the actor developer, not publicly. ### Support Found a bug or have a feature request? Open an issue in the Issues tab on this actor's page. For custom solutions or enterprise integrations, reach out through the Apify platform. # Actor input Schema ## `mode` (type: `string`): What you're starting from. hashtag (default) returns the videos popping under a tag. profiles ranks a set of creators. sounds finds who's riding a sound earliest. videos analyses specific video URLs. search ranks results for a query (off by default — must be acknowledged below). ## `hashtags` (type: `array`): One or more hashtags (with or without the #). Used in hashtag mode. The default run analyses #skincare. ## `rankBy` (type: `string`): How to order the results. breakoutPotential (default for hashtag/search) puts what's popping first. attention ranks by what to look at first overall. opportunity surfaces underserved upside. soundVirality ranks by sound-trend leverage (TikTok-only). Plus relevance, momentum, recency, engagement. ## `profiles` (type: `array`): TikTok handles (with or without @) for profiles mode. Each creator is ranked by who to look at first this week. ## `sounds` (type: `array`): TikTok sound/music URLs (or IDs) for sounds mode. Returns who is riding the sound earliest and whether its usage is accelerating. ## `videos` (type: `array`): TikTok video URLs for videos mode. Returns what's notable about each video. ## `searchQuery` (type: `string`): A free-text query for search mode. Search is off by default and requires the acknowledgement below. ## `searchModeAcknowledged` (type: `boolean`): Search runs against a path the platform asks automated tools not to use, so it is opt-in. Tick this to run search mode. Leave it off to use hashtag, profiles, sounds, or videos. ## `commentsSamplePerVideo` (type: `integer`): Collect up to this many public comments per video (any mode). At 30 or more you also get comment-theme synthesis: what viewers actually ask for, praise, and question. 0 = skip comments (fastest). ## `watchlistName` (type: `string`): Set a name to enable cross-run monitoring on ANY mode. The actor remembers this set and, on the next run, returns only what changed: new breakouts, surging sounds, creators going quiet — with a change briefing first. Use the same name on a schedule for a daily feed. ## `maxVideosPerHashtag` (type: `integer`): Cap on videos collected per hashtag (hashtag mode). Higher means a fuller cohort and more runtime. ## `maxRecentVideosPerProfile` (type: `integer`): Cap on recent videos collected per creator (profiles mode). Drives the creator's baseline window. ## `maxVideosPerSound` (type: `integer`): Cap on videos collected per sound (sounds mode). ## `maxResults` (type: `integer`): Cap on results collected for a search query (search mode). ## `outputProfile` (type: `string`): signals (default) adds the full decision layer — breakout, momentum, sound trends, attention queue, deltas. compat returns the exact standard TikTok-scraper field set for drop-in migration and raw ingestion (no decision layer). minimal returns IDs and URLs only. ## `taskPack` (type: `string`): Add a curated, product-shaped summary record built for a specific job — e.g. an emerging-creator shortlist or an opportunity list. Built from the same signals; no extra fetch. none = no pack. ## `changeWindowDays` (type: `integer`): Produce a 'what changed' read for the queried entities over this many days, drawn from tracked history — even without a prior watchlist run. Leave empty to skip. ## `proxyConfiguration` (type: `object`): Residential proxies are required — TikTok restricts automated access from datacenter IPs. The default uses Apify Residential with US rotation. Leave as-is unless you know you need a different region. ## Actor input object example ```json { "mode": "hashtag", "hashtags": [ "skincare" ], "rankBy": "breakoutPotential", "profiles": [ "@khaby.lame", "@nasa" ], "searchModeAcknowledged": false, "commentsSamplePerVideo": 0, "maxVideosPerHashtag": 100, "maxRecentVideosPerProfile": 50, "maxVideosPerSound": 100, "maxResults": 100, "outputProfile": "signals", "taskPack": "none", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "hashtag", "hashtags": [ "skincare" ], "rankBy": "breakoutPotential", "profiles": [ "@khaby.lame", "@nasa" ], "commentsSamplePerVideo": 0, "outputProfile": "signals" }; // Run the Actor and wait for it to finish const run = await client.actor("ryanclinton/tiktok-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "hashtag", "hashtags": ["skincare"], "rankBy": "breakoutPotential", "profiles": [ "@khaby.lame", "@nasa", ], "commentsSamplePerVideo": 0, "outputProfile": "signals", } # Run the Actor and wait for it to finish run = client.actor("ryanclinton/tiktok-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "hashtag", "hashtags": [ "skincare" ], "rankBy": "breakoutPotential", "profiles": [ "@khaby.lame", "@nasa" ], "commentsSamplePerVideo": 0, "outputProfile": "signals" }' | apify call ryanclinton/tiktok-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ryanclinton/tiktok-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Scraper — Breakouts, Creator Momentum & Sound Trends", "description": "TikTok Scraper with an attention layer: get ranked breakout videos, creator momentum, and trending TikTok sounds instead of rows. Works as a TikTok hashtag scraper, profile scraper, or sound tracker. Drop-in migration from clockworks/tiktok-scraper.", "version": "1.0", "x-build-id": "Ea4ls4DVicoEkRVFl" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ryanclinton~tiktok-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ryanclinton-tiktok-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/ryanclinton~tiktok-scraper/runs": { "post": { "operationId": "runs-sync-ryanclinton-tiktok-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/ryanclinton~tiktok-scraper/run-sync": { "post": { "operationId": "run-sync-ryanclinton-tiktok-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Input mode", "enum": [ "hashtag", "profiles", "sounds", "videos", "search" ], "type": "string", "description": "What you're starting from. hashtag (default) returns the videos popping under a tag. profiles ranks a set of creators. sounds finds who's riding a sound earliest. videos analyses specific video URLs. search ranks results for a query (off by default — must be acknowledged below).", "default": "hashtag" }, "hashtags": { "title": "Hashtags", "maxItems": 50, "type": "array", "description": "One or more hashtags (with or without the #). Used in hashtag mode. The default run analyses #skincare.", "items": { "type": "string" } }, "rankBy": { "title": "Rank by", "enum": [ "attention", "opportunity", "relevance", "breakoutPotential", "momentum", "recency", "engagement", "soundVirality" ], "type": "string", "description": "How to order the results. breakoutPotential (default for hashtag/search) puts what's popping first. attention ranks by what to look at first overall. opportunity surfaces underserved upside. soundVirality ranks by sound-trend leverage (TikTok-only). Plus relevance, momentum, recency, engagement." }, "profiles": { "title": "Profiles", "maxItems": 200, "type": "array", "description": "TikTok handles (with or without @) for profiles mode. Each creator is ranked by who to look at first this week.", "items": { "type": "string" } }, "sounds": { "title": "Sounds", "maxItems": 100, "type": "array", "description": "TikTok sound/music URLs (or IDs) for sounds mode. Returns who is riding the sound earliest and whether its usage is accelerating.", "items": { "type": "string" } }, "videos": { "title": "Videos", "maxItems": 500, "type": "array", "description": "TikTok video URLs for videos mode. Returns what's notable about each video.", "items": { "type": "string" } }, "searchQuery": { "title": "Search query", "type": "string", "description": "A free-text query for search mode. Search is off by default and requires the acknowledgement below." }, "searchModeAcknowledged": { "title": "Acknowledge search mode", "type": "boolean", "description": "Search runs against a path the platform asks automated tools not to use, so it is opt-in. Tick this to run search mode. Leave it off to use hashtag, profiles, sounds, or videos.", "default": false }, "commentsSamplePerVideo": { "title": "Comments sample per video", "minimum": 0, "maximum": 500, "type": "integer", "description": "Collect up to this many public comments per video (any mode). At 30 or more you also get comment-theme synthesis: what viewers actually ask for, praise, and question. 0 = skip comments (fastest).", "default": 0 }, "watchlistName": { "title": "Watchlist name", "type": "string", "description": "Set a name to enable cross-run monitoring on ANY mode. The actor remembers this set and, on the next run, returns only what changed: new breakouts, surging sounds, creators going quiet — with a change briefing first. Use the same name on a schedule for a daily feed." }, "maxVideosPerHashtag": { "title": "Max videos per hashtag", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on videos collected per hashtag (hashtag mode). Higher means a fuller cohort and more runtime.", "default": 100 }, "maxRecentVideosPerProfile": { "title": "Max recent videos per profile", "minimum": 1, "maximum": 500, "type": "integer", "description": "Cap on recent videos collected per creator (profiles mode). Drives the creator's baseline window.", "default": 50 }, "maxVideosPerSound": { "title": "Max videos per sound", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on videos collected per sound (sounds mode).", "default": 100 }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on results collected for a search query (search mode).", "default": 100 }, "outputProfile": { "title": "Output profile", "enum": [ "signals", "compat", "minimal" ], "type": "string", "description": "signals (default) adds the full decision layer — breakout, momentum, sound trends, attention queue, deltas. compat returns the exact standard TikTok-scraper field set for drop-in migration and raw ingestion (no decision layer). minimal returns IDs and URLs only.", "default": "signals" }, "taskPack": { "title": "Task pack", "enum": [ "none", "emergingCreatorDiscovery", "opportunityFinder", "competitorMonitor", "soundTrends", "breakouts" ], "type": "string", "description": "Add a curated, product-shaped summary record built for a specific job — e.g. an emerging-creator shortlist or an opportunity list. Built from the same signals; no extra fetch. none = no pack.", "default": "none" }, "changeWindowDays": { "title": "Change window (days)", "minimum": 1, "maximum": 180, "type": "integer", "description": "Produce a 'what changed' read for the queried entities over this many days, drawn from tracked history — even without a prior watchlist run. Leave empty to skip." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Residential proxies are required — TikTok restricts automated access from datacenter IPs. The default uses Apify Residential with US rotation. Leave as-is unless you know you need a different region.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```