# TikTok Discover Scraper (`clockworks/tiktok-discover-scraper`) Actor Scrape TikTok Discover data. Just add one or more hashtags and the scraper will extract related videos, tag breadcrumbs, similar trends, and subtopics. Export scraped data, run the scraper via API, schedule and monitor runs, or integrate with other tools. - **URL**: https://apify.com/clockworks/tiktok-discover-scraper.md - **Developed by:** [Clockworks](https://apify.com/clockworks) (Apify) - **Categories:** Social media, Videos - **Features:** Limited permissions - **Stats:** 668 total users, 20 monthly users, 100.0% runs succeeded, 30 bookmarks - **User rating**: 4.92 out of 5 stars ## Pricing from $1.50 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. 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. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## 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. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ### 📹 What is TikTok Discover Scraper? TikTok Discover Scraper is an easy-to-use scraping tool that allows you to **extract all TikTok videos from a chosen tag on `tiktok.com/discover` page**. Using this tool, you will be able to scrape: - **All TikToks posted** under a chosen Discover `tiktok.com/discover` page: caption, video URL, number of plays, hearts, comments, shares, country of creation, timestamp, paid or non-paid status, **video- and music-related metadata.** - **Basic creator info from TikToks posted** with chosen hashtags: name, ID, avatar, bio, account status, total followers/following numbers, given/received likes count, etc. - **Trend information** such as related hashtags, sub-topics, breadcrumbs ### 📹 How can I use data extracted from TikTok Discover? The data extracted from TikTok Discover Scraper can be used for a variety of purposes, including: 🦠 **Analyze trends**, viral campaigns, and content of specific creators 📚 Prepare for or analyze a **TikTok marketing campaign** ✨ Conduct sentiment analysis and find **authentic product reviews** 👩‍🔬 Obtain data for research and **social listening experiments** 🥸 **Identify unverified content** and inaccurate information with high public value ### 🎵 How do I export data from TikTok Discover page? Use TikTok Discover Scraper. It is designed to be user-friendly, offering a smooth start for those who have never extracted data from TikTok before. Here’s how you can use this web scraper to export TikTok videos: 1. [Create](https://console.apify.com/sign-up) a free Apify account using your email. 2. Open [TikTok Discover Scraper.](https://apify.com/clockworks/tiktok-discover-scraper) 3. Add one or more hashtags to scrape TikTok videos and creators. 4. Click the “Start” button and wait for the data to be extracted. 5. Download your data in JSON, XML, CSV, Excel, or HTML. If you want more guidance on how to use TikTok Discover Scraper, this [video tutorial](https://www.youtube.com/watch?v=W6G0mlpdQXI) shows you how to do it in just a few minutes. https://www.youtube.com/watch?v=W6G0mlpdQXI ### ⬇ Input The input for TikTok Discover Scraper should be one or multiple **TikTok hashtags**. Click on the [input tab](https://apify.com/clockworks/tiktok-discover-scraper/input-schema) for a full explanation of an input example in JSON. ```json { "hashtags": ["thailand"], "shouldDownloadCovers": false, "shouldDownloadSlideshowImages": false, "shouldDownloadSubtitles": false, "shouldDownloadVideos": false } ``` ### ⬆ Output sample The scraped TikTok videos will be shown as a dataset which you can find in the **Output tab**. Note that the output will first be organized as a table for viewing convenience. [![TikTok Discover page trends](https://raw.githubusercontent.com/apify-projects/actor-readme-images/af69bb0fd5048696d9332401fe7d834f8b71f937/tiktok%20discover%20data.png?raw=true)](https://console.apify.com/actors/DdSkpbFy5T8FyCsor/console/) You can preview all the fields and choose in which format to download the data you’ve extracted: JSON, CSV, Excel, HTML table, or XML. Here below is the same dataset in JSON: ```json [ { "id": "7328225833821244715", "text": "Waking up to this sunrise view was a DREAM ✨🇹🇭 📍 Samet Nangshe Boutique #thailand #thailandtravel #luxuryhotels #luxurytravel #bucketlist #traveltiktok ", "createTime": 1706235571, "createTimeISO": "2024-01-26T02:19:31.000Z", "isAd": false, "isMuted": false, "authorMeta": { "id": "6745789268591494150", "name": "hillarybowles", "nickName": "Hillary Bowles", "verified": false, "signature": "Fashion, travel, home decor and lots of love 🫶🏻\n💌hautewithhillary@gmail.com", "bioLink": null, "avatar": "https://p19-pu-sign-useast8.tiktokcdn-us.com/tos-useast5-avt-0068-tx/c01d6816e191dad8eb38baf339dc9b9f~c5_720x720.jpeg?lk3s=a5d48078&nonce=21298&refresh_token=b9a89b32c1699aa5b276f922df9f556f&x-expires=1716022800&x-signature=zxKFG0OD73zKXgp0zF%2BFheDqedc%3D&shp=a5d48078&shcp=b59d6b55", "privateAccount": false, "following": 370, "fans": 44900, "heart": 4100000, "video": 606, "digg": 88200 }, "musicMeta": { "musicName": "original sound", "musicAuthor": "HUGEL", "musicOriginal": true, "musicAlbum": "", "playUrl": "https://v16m.tiktokcdn-us.com/298241c186f169b7c432eee3f189313e/66462717/video/tos/useast2a/tos-useast2a-v-2370-euttp/oAJBAFD9HebfqtmsBlZYC4PZqbIUM9UlDZkFEQ/?a=1233&bti=NDU3ZjAwOg%3D%3D&ch=0&cr=0&dr=0&er=2&cd=0%7C0%7C0%7C0&br=250&bt=125&ft=GSDrKInz7ThovhzrXq8Zmo&mime_type=audio_mpeg&qs=6&rc=NzwzNDxpaWdlNGY7ZmlkOUBpMzhvOnA5cjlzcDMzZjU8M0AxNGAyNTI1NV8xMC8tMDE0YSNwNWhvMmRzLWBgLS1kMWNzcw%3D%3D&vvpl=1&l=20240516093206055B2F4D0691D7005A99&btag=e00088000&download=true", "coverMediumUrl": "https://p16-sign-useast2a.tiktokcdn.com/tos-useast2a-avt-0068-euttp/db06eb0816dc66fdb2b498d7de96e755~c5_720x720.jpeg?lk3s=a5d48078&nonce=62403&refresh_token=2b8a20261f958904863ba5cb5e772e9d&x-expires=1716022800&x-signature=%2FS7CSql4Y6onT2VLPNrj5bKsxVE%3D&shp=a5d48078&shcp=b59d6b55", "musicId": "7321041103715683104" }, "webVideoUrl": "https://www.tiktok.com/@hillarybowles/video/7328225833821244715", "mediaUrls": [ "https://v16-webapp-prime.us.tiktok.com/video/tos/useast5/tos-useast5-ve-0068c004-tx/oA8SQSAklDAXLyCoaxFhDRlg9EvgsBhsISfemE/?a=1988&bti=NDU3ZjAwOg%3D%3D&ch=0&cr=3&dr=0&lr=unwatermarked&cd=0%7C0%7C0%7C&cv=1&br=2178&bt=1089&cs=0&ds=6&ft=4KJMyMzD8Zmo0wd0Z-4jVAuZdpWrKsd.&mime_type=video_mp4&qs=0&rc=MzxpNmVoZzkzO2g0ZmY5ZUBpM3A4OWo5cjxrcDMzZzczNEAxMl40NV4vXjIxLi1gYGJgYSMtYzZtMmRjNm1gLS1kMS9zcw%3D%3D&btag=e00088000&expire=1716024736&l=20240516093206055B2F4D0691D7005A99&ply_type=2&policy=2&signature=15f58edb44aebb5348f1d10ee61a4624&tk=tt_chain_token" ], "videoMeta": { "height": 1024, "width": 576, "duration": 9, "coverUrl": "https://p16-sign.tiktokcdn-us.com/obj/tos-useast5-p-0068-tx/okESflIgSNAFAExLNRRshsfyxSD7DBMQvCWlkm?x-expires=1716022800&x-signature=yKfeqWWd4JkW%2BP%2FZRqXfAOAldd4%3D", "originalCoverUrl": "https://p16-sign.tiktokcdn-us.com/obj/tos-useast5-p-0068-tx/okESflIgSNAFAExLNRRshsfyxSD7DBMQvCWlkm?x-expires=1716022800&x-signature=yKfeqWWd4JkW%2BP%2FZRqXfAOAldd4%3D", "definition": "540p", "format": "mp4", "originalDownloadAddr": "https://v16-webapp-prime.us.tiktok.com/video/tos/useast5/tos-useast5-ve-0068c004-tx/oA8SQSAklDAXLyCoaxFhDRlg9EvgsBhsISfemE/?a=1988&bti=NDU3ZjAwOg%3D%3D&ch=0&cr=3&dr=0&lr=unwatermarked&cd=0%7C0%7C0%7C&cv=1&br=2178&bt=1089&cs=0&ds=6&ft=4KJMyMzD8Zmo0wd0Z-4jVAuZdpWrKsd.&mime_type=video_mp4&qs=0&rc=MzxpNmVoZzkzO2g0ZmY5ZUBpM3A4OWo5cjxrcDMzZzczNEAxMl40NV4vXjIxLi1gYGJgYSMtYzZtMmRjNm1gLS1kMS9zcw%3D%3D&btag=e00088000&expire=1716024736&l=20240516093206055B2F4D0691D7005A99&ply_type=2&policy=2&signature=15f58edb44aebb5348f1d10ee61a4624&tk=tt_chain_token", "downloadAddr": "https://v16-webapp-prime.us.tiktok.com/video/tos/useast5/tos-useast5-ve-0068c004-tx/oA8SQSAklDAXLyCoaxFhDRlg9EvgsBhsISfemE/?a=1988&bti=NDU3ZjAwOg%3D%3D&ch=0&cr=3&dr=0&lr=unwatermarked&cd=0%7C0%7C0%7C&cv=1&br=2178&bt=1089&cs=0&ds=6&ft=4KJMyMzD8Zmo0wd0Z-4jVAuZdpWrKsd.&mime_type=video_mp4&qs=0&rc=MzxpNmVoZzkzO2g0ZmY5ZUBpM3A4OWo5cjxrcDMzZzczNEAxMl40NV4vXjIxLi1gYGJgYSMtYzZtMmRjNm1gLS1kMS9zcw%3D%3D&btag=e00088000&expire=1716024736&l=20240516093206055B2F4D0691D7005A99&ply_type=2&policy=2&signature=15f58edb44aebb5348f1d10ee61a4624&tk=tt_chain_token" }, "diggCount": 82000, "shareCount": 7254, "playCount": 1100000, "collectCount": 33600, "commentCount": 251, "mentions": [], "hashtags": [ { "id": "9128", "name": "thailand", "title": "🇹🇭 hi Thailand!!!😘😘😘 🇹🇭", "cover": "" }, { "id": "40201396", "name": "thailandtravel", "title": "", "cover": "" }, { "id": "1625911277616134", "name": "luxuryhotels", "title": "", "cover": "" }, { "id": "4872557", "name": "luxurytravel", "title": "", "cover": "" }, { "id": "260248", "name": "bucketlist", "title": "Whether it's starting a new hobby or planning a dream trip, show us what's on your #BucketList.", "cover": "" }, { "id": "1598183468378114", "name": "traveltiktok", "title": "The countdown to summer has begun!🌞 Start planning your epic summer destinations with our expert recommendations . 📆🌴", "cover": "https://p58-sg.tiktokcdn.com/obj/tiktok-obj/ebbaceb0a4bb866c60bf7a9fd2a4ed98.png" } ], "effectStickers": [], "isSlideshow": false, "isPinned": false, "input": "thailand", "discoveryInfo": { "breadcrumbs": [], "relatedTags": [], "url": "https://www.tiktok.com/discover/thailand", "tag": "thailand", "type": "discover" } } ] ``` ### 🎸 Want to scrape TikTok comments, creators or music? If you want to scrape TikTok beyond just TikTok Discover data, you can use one of the specialized web scrapers below, each built particularly for the relevant TikTok scraping case, whether it's profiles, comments, search results, or all data at once:
📹 Tiktok Video Scraper 🧛 TikTok Profile Scraper 🎸 Tiktok Sound Scraper #️⃣ TikTok Ads Scraper
🎙 TikTok Comments Scraper 🎶 TikTok Scraper #️⃣ TikTok Hashtag Scraper 🎵 TikTok Data Extractor
### ❓FAQ #### How much does TikTok Discover cost? TikTok Discover Scraper uses the Pay-per-event model, so your costs can be easily calculated. It’ll cost you: - $0.03 for starting the scraper - $0.0030 for every dataset item - $0.0010 for every downloaded video Apify free plan gives you $5 of prepaid credits. With that, you can start the Actor once and get 1,656 dataset items. Or start the Actor, get 1,322 dataset items, and download 1,000 videos. Or start the Actor, get 1,649 dataset items, and download 500 videos. You get the drill. #### Is there a TikTok Discover API? Unfortunately, there's no TikTok Discover API. However, you can use scrapers and crawlers as a stand-in for an API, e.g. 📢 [TikTok Discover Scraper](https://apify.com/clockworks/tiktok-discover-scraper). #### Can I integrate TikTok Discover Scraper with other apps? Yes. **Tiktok Discover Scraper can be connected with almost any cloud service or web app** thanks to integrations on the Apify platform. You can integrate with Make, Zapier, LangChain, Asana, Slack, Airbyte, GitHub, Google Sheets, Google Drive, and more. You can also integrate with other Actors. Or you can use webhooks to carry out an action whenever an event occurs, e.g., get a notification whenever Tiktok Discover Scraper successfully finishes a run. #### Can I use TikTok Discover Scraper with the API? Yes, you can do so by using Apify API. It gives you programmatic access to the Apify platform. The API is organized around RESTful HTTP endpoints that enable you to manage, schedule, and run Apify Actors. The API also lets you access any datasets, monitor actor performance, fetch results, create and update versions, and more. To access the API using Node.js, use the `apify-client` NPM package. To access the API using Python, use the `apify-client` PyPI package. Check out the [Apify API reference](https://docs.apify.com/api/v2) docs for full details, or click on the [API tab](https://apify.com/clockworks/tiktok-discover-scraper/api) for code examples. #### Can I use this TikTok Discover API in Python? Yes, by using Apify API. To access the [TikTok Discover API using Python](https://apify.com/clockworks/tiktok-discover-scraper/api/client/python), use the `apify-client` PyPI package. You can find more details about the client in our [Docs for Python Client](https://docs.apify.com/api/client/python/). #### Is it legal to scrape videos from TikTok Discover? Our [TikTok scrapers](https://apify.com/store?search=tiktok) are ethical and **do not extract any private user data, such as email addresses, gender, or location.** They can only extract what the user has chosen to share publicly. However, you should be aware that your results might contain personal data. Personal data is protected by GDPR in the European Union and other laws and regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you’re unsure whether your reason is legitimate, consult your lawyers. You can also read our blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/) and [ethical scraping](https://blog.apify.com/what-is-ethical-web-scraping-and-how-do-you-do-it/). #### Not your cup of tea? Build your own scraper. TikTok Discover Scraper doesn’t exactly do what you need? You can always build your own! We have various [scraper templates](https://apify.com/templates) in Python, JavaScript, and TypeScript to get you started. Alternatively, you can write it from scratch using our [open-source library Crawlee](https://crawlee.dev/). You can keep the scraper to yourself or make it public by adding it to the Apify Store (and [find users](https://apify.com/partners/actor-developers) for it). #### Your feedback We’re always working on improving the performance of our [Actors](https://apify.com/actors). So if you’ve got any technical feedback for TikTok Discover Scraper or simply found a bug, please create an issue on the Actor’s [Issue tab](https://apify.com/clockworks/tiktok-discover-scraper/issues/open). ### Error items When the scraper cannot retrieve data for a given input — for example a profile is private or a post has been deleted — it pushes an **error item** to the dataset instead of silently skipping it. Normal output items are never affected; you can tell them apart by the presence of an `errorCode` field. #### Error item structure ```json { "url": "https://www.tiktok.com/@someuser", "input": "someuser", "error": "Profile is private", "errorCode": "PROFILE_PRIVATE" } ``` #### Error codes reference | `errorCode` | Meaning | | -------------------------------- | -------------------------------------------------------------- | | `NOT_FOUND` | Profile or hashtag does not exist | | `POST_NOT_FOUND_OR_PRIVATE` | Post URL is gone or private | | `POST_SENSITIVE` | Post is flagged as sensitive content | | `NO_TRENDING_FOR_HASHTAG` | No ads found for this hashtag | | `MUSIC_NOT_FOUND` | No videos found for the music tag | | `SEARCH_QUERY_NOT_FOUND` | No videos found for the search query | | `SEARCH_QUERY_PROFILE_NOT_FOUND` | No profiles found for the search query | | `FILTER_NO_PASS` | Videos exist but none match the active date/popularity filters | | `PROFILE_EMPTY` | Profile has no videos (or is behind a login wall) | | `PROFILE_REPOSTS_EMPTY` | Profile has no reposts (or is behind a login wall) | | `PROFILE_VIDEOS_UNAVAILABLE` | Profile has videos, but TikTok returned none (login wall) | | `PROFILE_FOLLOWING_EMPTY` | Profile is not following anyone | | `PROFILE_FOLLOWERS_EMPTY` | Profile has no followers | | `PROFILE_PRIVATE` | Profile is private | | `GOOGLE_RUN_NO_RESULTS` | Google-assisted run returned no results | | `TRENDING_EMPTY` | Trending page returned no results | | `INVALID_INPUT` | Actor failed due to bad configuration (run is also terminated) | | `INVALID_URLS` | One or more start URLs were malformed | # Changelog This Actor's version history is a separate document: https://apify.com/clockworks/tiktok-discover-scraper/changelog.md # Actor input Schema ## `hashtags` (type: `array`): Just add TikTok hashtags and the scraper will collect information. ## `resultsPerPage` (type: `integer`): Maximum number of posts that will be scraped from every hashtag. ## `shouldDownloadVideos` (type: `boolean`): Tick to download TikTok videos. Note that this will increase time and costs needed to extract the data. One downloaded video costs you $0.001. ## `shouldDownloadCovers` (type: `boolean`): Tick to download TikTok video cover images (thumbnails). Note that this will increase time and costs needed to extract the data. ## `downloadSubtitlesOptions` (type: `string`): Choose how to handle subtitles and audio transcription for input videos. Subtitles are provided by TikTok for some videos, and transcription means that this Actor will use speech-to-text AI to generate video transcript. Transcripts are charged as an extra event according to your plan. ## `shouldDownloadSlideshowImages` (type: `boolean`): Tick to download TikTok slideshow images. Note that this will increase costs and time required for scraping. ## `videoKvStoreIdOrName` (type: `string`): Name (or ID) of the Key Value Store where the videos and other media like thumbnails will be stored. Omit to store in the default one. Using this option will provide a named Key-Value store can help bypass data retention and store the content forever until the store is manually deleted.

The Key-Value store's name can consist of a versatile combination of uppercase letters, lowercase letters, digits, or hyphens, all without any spaces. ## Actor input object example ```json { "hashtags": [ "tokyo" ], "resultsPerPage": 100, "shouldDownloadVideos": false, "shouldDownloadCovers": false, "downloadSubtitlesOptions": "NEVER_DOWNLOAD_SUBTITLES", "shouldDownloadSlideshowImages": false, "videoKvStoreIdOrName": "tiktok-videos" } ``` # Actor output Schema ## `dataset` (type: `string`): Dataset containing all scraped data # 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 = { "hashtags": [ "tokyo" ] }; // Run the Actor and wait for it to finish const run = await client.actor("clockworks/tiktok-discover-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 = { "hashtags": ["tokyo"] } # Run the Actor and wait for it to finish run = client.actor("clockworks/tiktok-discover-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "hashtags": [ "tokyo" ] }' | apify call clockworks/tiktok-discover-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,clockworks/tiktok-discover-scraper" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/DdSkpbFy5T8FyCsor/builds/I76o9Xom1nRggiVEh/openapi.json