# TikTok Trending Videos Scraper (`socialdataapi/tiktok-trending-videos-scraper`) Actor TikTok Trending Videos Scraper collects videos trending on TikTok by country: views, likes, comments, shares, bookmarks, author, caption and date. Sort by metric, filter last 7 or 30 days, or scrape your own video links. Export to JSON, CSV or Excel, or use the API. - **URL**: https://apify.com/socialdataapi/tiktok-trending-videos-scraper.md - **Developed by:** [Social Data API](https://apify.com/socialdataapi) (community) - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.36 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 ### TikTok Trending Videos Scraper — Views, Likes, Shares and Authors TikTok Trending Videos Scraper collects the videos currently trending on TikTok for the country you choose. For each video it returns the view, like, comment, share and bookmark counts, the author, caption, publish date and cover image, plus hashtags, music and follower counts when you want more detail. Every response is structured JSON — ready to pass directly to an LLM, index into a vector store, or feed a content trend analysis pipeline. **No TikTok account or cookies needed.** Start with one country, then track every market you post in. ![TikTok Trending Videos Scraper returns trending TikTok videos by country with views, likes, hashtags and creator data as JSON](https://api.apify.com/v2/key-value-stores/WYkyEfqs10huyXYxr/records/e-tiktok-trending-videos-hero.webp) *** ### What data can I extract with TikTok Trending Videos Scraper? Using this TikTok Video API, you will be able to extract the following TikTok video data: | 🎬 Video ID and link | 📝 Caption (title) | 👁️ View count | ❤️ Like count | |---|---|---|---| | 💬 Comment count | 🔁 Share count | 🔖 Bookmark count | 📅 Publish date and time | | ⏳ Duration in seconds | 🖼️ Cover image | 👤 Author handle and name | 🌍 Requested country and served region | | 📌 Hashtags (detailed data) | 🎵 Music title, author and link (detailed data) | 👥 Author follower and following counts (detailed data) | ✅ Verified badge (detailed data) | | 🧾 Author bio, avatar and profile link (detailed data) | 📊 Total engagement and engagement rate (detailed data) | 📹 Direct video file link (detailed data) | 📐 Video width, height, quality and format (detailed data) | | 📢 Ad flag (detailed data) | 🗣️ Caption language (detailed data) | 🕒 Scrape time | | *** ### How to use TikTok Trending Videos Scraper Social media marketers, creators and trend researchers use it to scrape trending TikTok videos: they get a ranked list of what is trending on TikTok in one country from a single run, or fresh stats for any videos they already track. **Copy to your AI assistant:** ```text TikTok Trending Videos Scraper is an Apify Actor (Apify Actor ID: socialdataapi/tiktok-trending-videos-scraper, https://apify.com/socialdataapi/tiktok-trending-videos-scraper) that returns the videos currently trending on TikTok for a chosen country, or the videos behind a list of TikTok links, as structured JSON: video link, caption, view count, like count, comment count, share count, bookmark count, author handle, publish date, and with detailed data on also hashtags, music, author follower counts, engagement rate and a direct video file link. Use it whenever someone needs TikTok trending videos without cookies, a login, or a browser - spotting what is going viral in a market, picking sounds and hashtags for new content, refreshing view and like counts for a list of campaign videos. Run it with curl by sending a POST with -H "Content-Type: application/json" and the body '{"countryCode":"US","sortBy":"vv","period":"30","maxItems":5,"includeDetailedVideoData":true,"proxyConfiguration":{"useApifyProxy":true}}' to this Actor's run-sync-get-dataset-items endpoint in the Apify API with token=APIFY_TOKEN. Or in Python: ApifyClient("APIFY_TOKEN").actor(...).call(run_input={"countryCode": "US", "maxItems": 5}) with this Actor's ID, then client.dataset(run["defaultDatasetId"]).list_items().items. Inputs: videoUrls (array of strings, optional, TikTok video links; when filled, exactly those videos are scraped instead of trending ones, default []), countryCode (string, country of the trending videos, "AU"|"BR"|"CA"|"EG"|"FR"|"DE"|"ID"|"IL"|"IT"|"JP"|"MY"|"PH"|"RU"|"SA"|"SG"|"KR"|"ES"|"TW"|"TH"|"TR"|"AE"|"GB"|"US"|"VN", default "US"), sortBy (string, ranking metric, "vv" views|"like"|"comment"|"repost" shares, default "vv"), period (string, only videos published in the last N days, "7"|"30", default "30"), maxItems (integer 1-1000, number of trending videos to deliver, default 10), includeDetailedVideoData (boolean, adds hashtags, music, author stats, video file link and engagement metrics, default false), proxyConfiguration (object, Apify proxy settings; keep it on so the country is honoured, default Apify proxy on). Billing: one row_result event per video saved to the dataset; links that are not TikTok links, duplicates and videos without data add no rows and cost nothing. Every row has the same core keys, trending rows also carry the chosen period, detailed keys appear when detailed data is on, and the served region shows which country TikTok actually served. A run delivers fewer than maxItems when TikTok has fewer trending videos in the chosen period, and the run's status message says so. Full input schema, every enum and default, and the complete output field list: GET this Actor's builds/default endpoint in the Apify API. ``` #### TikTok Trending Videos Scraper MCP Server: use these Actors from ChatGPT, Claude or Cursor Point your AI assistant at the Apify MCP server scoped to this Actor and it can read TikTok trending videos on its own: the server's call actor tool runs it for you directly, no searching or adding required. No glue code, no scraping logic in your prompts. ```bash claude mcp add --transport http apify "https://mcp.apify.com?tools=socialdataapi/tiktok-trending-videos-scraper" ``` #### Step by step 1. [Create a free Apify account](https://console.apify.com/sign-up). 2. Open [TikTok Trending Videos Scraper](https://apify.com/socialdataapi/tiktok-trending-videos-scraper) in the Apify Store. 3. Pick the TikTok country, sort order, period and number of videos, or paste TikTok video links. 4. Click **Start** (or send your API request). 5. Download or stream your results in JSON, CSV or Excel. #### How to scale TikTok Trending Videos Scraper to bulk One run delivers up to 1,000 trending videos for one country, so a single run already covers a deep ranking. To get TikTok trending videos by country, start one run per country through the Apify API or a schedule, for example a daily run for the United States, the United Kingdom and Brazil. To refresh the numbers of videos you already follow, put all their links into Video links in one run; each video becomes one row, and a video listed twice is scraped once. From the Output tab you can export trending TikTok videos to CSV, Excel or JSON, or read them through the dataset API. *** ### ✨ Features TikTok Trending Videos Scraper fetches clean, structured videos from TikTok ⚡. It's ideal for trend spotting by country, picking viral sounds and hashtags, benchmarking creators, and feeding AI agents with what people watch right now. It works as a TikTok trending scraper, a TikTok popular videos scraper ranked by views, likes, comments or shares, and a TikTok video stats scraper for links you supply. It extracts, per video: - **View count** – how many times the video was played - **Like, comment, share and bookmark counts** – the engagement behind each video - **Video link and caption** – where to watch it and what it says - **Author handle and name** – who posted it - **Publish date** – when it went live, in UTC - **Engagement rate** – likes, comments, shares and bookmarks per view, in percent (detailed data) - **Hashtags and music** – the tags and the sound used (detailed data) - **Served region** – the country TikTok actually served the trending list for ⚡ A metric TikTok does not return stays empty instead of being filled with a made-up zero, and links that give no video data are not charged. *** ### Use cases 💡 - **Social media manager** — check the top viewed trending videos in a market before planning the week. - **Creator** — pick sounds and hashtags from viral videos posted in the last 7 days. - **Brand marketer** — compare trending videos by country across the US, UK and Brazil. - **Agency analyst** — refresh view and like counts for a list of campaign video links. - **AI agent builder** — feed trending captions and engagement rates into a RAG trend assistant. Building an AI agent? [Connect TikTok Trending Videos Scraper over MCP](#mcp-integration-for-ai-agents) and let it call the actor on its own. *** ### Why choose this actor? - **A ranked trending list in seconds.** A recorded run returned 5 trending videos with all 52 fields each, ranked by views, in 5.4 seconds; a run for 2 video links took 2.6 seconds. - **The numbers behind each video.** A recorded trending video came back with 10,400,000 views, 259,400 likes, 105,500 shares, 62,000 bookmarks and a 4.16% engagement rate, plus its author's 30,700 followers. - **Two modes, 24 countries, four rankings.** Trending discovery or your own video links; 24 countries; ranking by views, likes, comments or shares; a 7-day or 30-day window. *** ### ⬇️ Input ![TikTok Trending Videos Scraper input: country, period, max items and video links](https://api.apify.com/v2/key-value-stores/WYkyEfqs10huyXYxr/records/e-tiktok-trending-videos-input.webp) The actor takes either nothing but filters (country, sort order, period, number of videos) for trending mode, or a list of TikTok video links. No field is required; with an empty form it returns 10 trending videos for the United States from the last 30 days. | Parameter | Required | Type | Description | Example value | |---|---|---|---|---| | `videoUrls` | No | array of strings | TikTok video links. When filled, exactly these videos are scraped instead of trending ones; non-TikTok links are skipped and a video listed twice is scraped once. Default `[]`. | `["https://www.tiktok.com/@chota.toon/video/7688347739301645575"]` | | `countryCode` | No | string | Country of the trending videos: AU, BR, CA, EG, FR, DE, ID, IL, IT, JP, MY, PH, RU, SA, SG, KR, ES, TW, TH, TR, AE, GB, US, VN. Honoured through a proxy in that country. Default `US`. | `"US"` | | `sortBy` | No | string | Ranking, highest first: `vv` (views), `like`, `comment`, `repost` (shares). Default `vv`. | `"vv"` | | `period` | No | string | Only videos published in the last `7` or `30` days. Default `30`. | `"30"` | | `maxItems` | No | integer | Number of trending videos to deliver, 1–1000. Not used with video links. Default `10`. | `5` | | `includeDetailedVideoData` | No | boolean | Adds hashtags, music, author bio and stats, direct video file link, video size and format, ad flag and engagement metrics. Default `false`. | `true` | | `proxyConfiguration` | No | object | Proxy settings. Keep the Apify proxy on so the country is honoured; the run may switch to residential proxies in your country. Default Apify proxy on. | `{"useApifyProxy": true}` | #### Free plan limits Users on the Apify free plan can fetch up to 20 videos per run (trending videos and video links together) and 200 videos per month. When the limit is reached, the run finishes successfully with a status message explaining the limit. Upgrade to any paid Apify plan to remove these limits. #### Example input This is the input of the recorded test run shown below. It ran on a local machine without an Apify proxy, so TikTok served the trending list of that machine's own country (the served region in the output). On Apify, keep the proxy on to get the country you pick. ```json { "countryCode": "US", "sortBy": "vv", "period": "30", "maxItems": 5, "includeDetailedVideoData": true, "proxyConfiguration": { "useApifyProxy": false } } ``` *** ### ⬆️ Output ![TikTok Trending Videos Scraper output: one JSON row per video with views, hashtags, authorUniqueId and engagementRate](https://api.apify.com/v2/key-value-stores/WYkyEfqs10huyXYxr/records/e-tiktok-trending-videos-output.webp) Every video is one typed, normalized JSON item with the same schema on every run; trending rows also carry the chosen period, and detailed fields appear when detailed data is on. You can export the results as JSON (default), CSV or Excel. #### Example output The first row of the recorded run above (real values; the cover, music and video links are temporary and expire after some time). The served region is "BD" because that test ran without a proxy from a machine in Bangladesh: the region always follows the country of the proxy, so with the Apify proxy on it matches the country you pick. ```json { "type": "video", "sourceMode": "discovery", "id": "7688347739301645575", "item_id": "7688347739301645575", "webVideoUrl": "https://www.tiktok.com/@chota.toon/video/7688347739301645575", "title": "যে বাচ্চারা সারদিন মোবাইল দেখে পড়াশোনা করে না, তাদেরকে এই বাচ্চার মত ধরে আনবো কিন্তু #kids #cartoon #kidssong #foryou #fyp ", "cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/oE4kRqMrsFLEEfLoBAQbgw9fdj1glFIDCAcB4n~tplv-tiktokx-origin.image?dr=14575&x-expires=1791367200&x-signature=vgFkC0nFceexKbIJxxTA4tzwmHE%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my2", "duration": 20, "createTime": 1790082957, "createTimeISO": "2026-09-22T13:15:57.000Z", "authorUniqueId": "chota.toon", "authorNickname": "Chota Toon", "views": 10400000, "likes": 259400, "comments": 6167, "shares": 105500, "bookmarks": 62000, "item_url": "https://www.tiktok.com/@chota.toon/video/7688347739301645575", "country_code": "US", "region": "BD", "period": "30", "desc": "যে বাচ্চারা সারদিন মোবাইল দেখে পড়াশোনা করে না, তাদেরকে এই বাচ্চার মত ধরে আনবো কিন্তু #kids #cartoon #kidssong #foryou #fyp ", "hashtags": ["kids", "cartoon", "kidssong", "foryou", "fyp"], "authorId": "7685505548657853441", "authorVerified": false, "authorFollowers": 30700, "authorFollowing": 25, "authorHearts": 310700, "authorVideoCount": 103, "authorAvatar": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/254b29a2dd9a7b3d66486abc32dd62ae~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=14579&refresh_token=169c7ae3&x-expires=1791367200&x-signature=ukDJsd%2F2JuzKer7ZOYMg1MVKacE%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=my2", "authorBio": "🧸 Welcome to Chota Toon! 🌈\n👶 Cute AI Cartoon Stories", "authorUrl": "https://www.tiktok.com/@chota.toon", "musicId": "7688347755725261588", "musicTitle": "original sound", "musicAuthor": "Chota Toon", "musicPlayUrl": "https://v16m.tiktokcdn.com/cee1860629d0e741362824d858943a9b/6ac4d4a7/video/tos/alisg/tos-alisg-v-27dcd7/o0DNAVPCg5eEoyFTymIAy4EgNfAfIOjkAFZI4D/?a=1180&bti=ODszNWYuMDE6&&bt=125&ft=GcDrcInz7Th~Ax-GXq8Zmo&mime_type=audio_mpeg&rc=M211NGs5cjY6ZDMzODU8NEBpM211NGs5cjY6ZDMzODU8NEAvbWhsMmRrc21hLS1kMS1zYSMvbWhsMmRrc21hLS1kMS1zcw%3D%3D&vvpl=1&l=20261005185931D40CD383F4EC68CD96E1&btag=e00078000&sp_exp=hash_v0", "musicDuration": 20, "musicOriginal": true, "videoUrl": "https://v16-webapp.tiktok.com/98f83edb194ee6f1a71708421df07730/6ac62627/video/tos/alisg/tos-alisg-pve-0037c001/oooDFBjrnEw5gl9kQgC5Ef4dcfscqIALBBARgF/?a=1988&bti=ODszNWYuMDE6&&bt=590&ft=-Elcomr3PD12NJaion-Ux~L59Y6e3wv25-cAp&mime_type=video_mp4&rc=O2VlN2g6NTZlNzY1ZDhoZEBpM2o5c3I5cnE6ZDMzODczNEBjNC82XmFeNWIxNV80YS8wYSNiLWJeMmRjcm1hLS1kMWBzcw%3D%3D&vvpl=1&l=20261005185931D40CD383F4EC68CD96E1&btag=e00078000", "videoWidth": 576, "videoHeight": 1024, "videoRatio": "540p", "videoDefinition": "540p", "videoFormat": "mp4", "videoBitrate": 604589, "originCover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/okrQ4TgLBDfsjcAkj4F1g9QERAw9BCdfE1Bqhn~tplv-tiktokx-origin.image?dr=14575&x-expires=1791367200&x-signature=kVLXochUjRvXUu1kzGJBBOkZBc8%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my2", "dynamicCover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/oUBJAMDfjfMZA4MVsXr98Diuh6CI7QkA4CPxCe~tplv-tiktokx-origin.image?dr=14575&x-expires=1791367200&x-signature=5F8TzLWxzlz3XVqAQoshvrl28jk%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my2", "textLanguage": "bn", "isAd": false, "totalEngagement": 433067, "engagementRate": 4.1641, "scrapedAt": "2026-10-05T10:59:15.000Z" } ``` *** ### How does it work? The actor opens TikTok's public pages in a real browser and handles rendering automatically, so it sees the same trending videos any visitor in the chosen country sees — no TikTok account, no login, no cookies. TikTok decides which videos are trending from the country the connection comes from. The actor therefore looks for a working proxy in the country you pick and, when the default proxies have none or stop giving new videos, switches to residential proxies in that country through a new connection. It collects until it has the number of videos you asked for or reaches its time limit, keeps only those from your chosen period, and ranks them by your chosen metric. For video links it first loads each page with a plain request and opens the browser only when needed. Field names and types stay the same on every run. *** ### How do you integrate TikTok Trending Videos Scraper into your stack? It works with what you already use: the REST API from any language, MCP for AI agents, and no-code tools. Through the Apify API it acts as a TikTok trending videos API that returns the dataset items as JSON. #### MCP integration for AI agents Add the Apify MCP server, scoped to this Actor, to your agent with one command: ```bash claude mcp add --transport http apify "https://mcp.apify.com?tools=socialdataapi/tiktok-trending-videos-scraper" ``` This registers the Apify MCP server with this Actor already available, so its call actor tool lets your agent run it directly — no searching or adding required. It works in Claude Code, Cursor and Windsurf, and in any other client that supports MCP over HTTP. Your agent passes the country and number of videos and gets the trending videos back as JSON. #### No-code tools (n8n, Make, LangChain) - **n8n** — add the Apify node, choose "Run an Actor" and pick this Actor, or use the HTTP Request node pointed at the run-sync endpoint with your token. Each trending video comes back as a workflow item. - **Make** — use the Apify app's "Run an Actor" module with your country and number of videos, then the "Get Dataset Items" module to pass each video to the next step. - **LangChain** — install `langchain-apify` and wrap this Actor with `ApifyActorsTool`, using its ID from the Apify Store page, so your agent can request trending videos as a tool call. *** ### Is it legal to scrape TikTok data? Scraping publicly available TikTok data is generally legal, as long as you collect only what is visible without logging in and use it responsibly. TikTok Trending Videos Scraper returns only publicly available data — what any user sees without logging in: public videos, their counts, captions and public author details. Under GDPR, scraping public data is generally permissible, but storing and using it, especially author names and bios, must comply with local data-protection law. This is not legal advice. Consult legal counsel if your use case involves bulk storage of personal data. *** ### Frequently asked questions #### What fields does TikTok Trending Videos Scraper return? It returns the video link, caption, view count, like count and publish date of each video, along with comment, share and bookmark counts, the author and the served region. With detailed data on you also get hashtags, music, author follower counts, engagement rate and a direct video file link. See [the data fields section](#what-data-can-i-extract-with-tiktok-trending-videos-scraper). #### Does TikTok Trending Videos Scraper require a TikTok account or login? No. Only public TikTok video data is extracted. No credentials, cookies or keys are needed. #### How fast does TikTok Trending Videos Scraper run? In recorded test runs, 5 trending videos with all fields took 5.4 seconds, and 2 video links took 2.6 seconds. Every run reads live data from TikTok, not a cache; larger numbers of videos and the 7-day period take longer. #### What happens if a video is private or doesn't exist? The link is skipped with a warning in the log, no row is added and nothing is charged. The run's status message counts the links without video data, so in code you can compare the number of rows with the number of links you sent. #### Can I scrape multiple TikTok videos at once? Yes. Trending mode delivers up to 1,000 videos per run, and video-link mode takes any list of TikTok video links in one run, one row per video, so it also serves as a TikTok video views scraper for the videos you track. #### Does TikTok Trending Videos Scraper work with Claude, ChatGPT, and other AI agent tools? Yes — TikTok Trending Videos Scraper is available as an MCP tool through the Apify MCP server. Register it in Claude Code, Cursor or Windsurf with: ```bash claude mcp add --transport http apify "https://mcp.apify.com?tools=socialdataapi/tiktok-trending-videos-scraper" ``` Any agent that can call an HTTP endpoint can also use the REST API directly. #### Does TikTok Trending Videos Scraper return data in a format LLMs can use directly? Yes. It returns typed, normalized JSON with consistent field names. No HTML parsing, no selectors. Pass it straight to an LLM, index it into a vector store, or feed it to an agent tool — no transformation step. #### What happens when TikTok changes its layout or updates its anti-bot system? The output keeps the same field names and types on every run; a value TikTok stops sending comes back empty instead of being guessed. If a TikTok change stops the actor from finding videos, the run says so in its status message instead of returning made-up data. #### Can I use TikTok Trending Videos Scraper without managing proxies or browser infrastructure? Yes. The proxy choice, the switch to residential proxies when needed and the browser all run on the actor's side. You send one request and get structured JSON back. No proxy accounts, no headless browser setup, no maintenance. #### Which TikTok video fields work best for AI training data and RAG indexing? For RAG, use the text-rich fields: the caption, hashtags, author bio and music title. For training data, use the numeric and boolean fields: view count, like, comment, share and bookmark counts, engagement rate, duration, follower count and the verified badge. All fields are typed primitives — strings, integers, booleans — so no normalization is needed. *** ### Your feedback Found a bug or missing a field? Let us know through the Issues tab of this Actor in Apify Console. Every report is read, and fixes ship in new builds so this TikTok viral videos scraper keeps matching what TikTok shows. # Actor input Schema ## `videoUrls` (type: `array`): Leave this empty to scrape trending videos (the normal mode). If you add TikTok video links (for example https://www.tiktok.com/@user/video/1234567890123456789), the run scrapes exactly those videos instead, one row per video. Sort by, Period and Max items do not apply in this mode; Country is still used to pick the proxy country. Links that are not TikTok links are skipped and not charged, and a video listed twice is scraped once. Free plan: up to 20 videos per run (all video links together) and 200 per month; paid plans have no limit. ## `countryCode` (type: `string`): Country whose trending videos you want. TikTok shows trending videos based on where the connection comes from, so this country is honoured when the Apify proxy below is turned on (the run then uses a proxy in this country). The country TikTok actually served is written to every trending row as the served region and shown in the log. ## `sortBy` (type: `string`): Order of the delivered videos, highest first: by view count, like count, comment count or share count. The ranking is applied to the trending videos collected in this run. ## `period` (type: `string`): Only keep videos published within the last 7 or 30 days. 30 days is the default because only a small share of trending videos is less than a week old: with 7 days a large Max items value can run out of eligible videos, and the run then says so in its status message. ## `maxItems` (type: `integer`): How many trending videos to deliver (1-1000). The run keeps collecting until it has this many or reaches its time limit; if fewer are available, it delivers what it found and says so in the status message. Not used when Video links are given. Free plan: up to 20 videos per run and 200 per month; paid plans have no limit. ## `includeDetailedVideoData` (type: `boolean`): Off: each row has the core fields (video ID and link, caption as title, cover image, duration, publish date, author handle and name, views, likes, comments, shares, bookmarks). On: each row also gets the full caption, hashtags, author ID, bio, avatar, verified badge and follower, following, likes and video counts, music details, a direct video file link, video size, quality and format, the ad flag, total engagement and engagement rate. ## `proxyConfiguration` (type: `object`): Proxy used for every request. Keep the Apify proxy on: TikTok picks the trending country from where the connection comes from, so Country above is only honoured through a proxy in that country. The run looks for a working proxy in your country and may switch to residential proxies (in your country) when the default proxies have none or stop returning new videos; residential traffic can cost more on your Apify plan. If you choose specific proxy groups, the run may still switch to residential proxies for later new connections. Your own proxy URLs are used as given. Turn the proxy off only if you want whatever country this run's own connection gets. ## Actor input object example ```json { "videoUrls": [], "countryCode": "US", "sortBy": "vv", "period": "30", "maxItems": 10, "includeDetailedVideoData": false, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `results` (type: `string`): All scraped videos in the default dataset, overview view. # 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 = { "videoUrls": [], "countryCode": "US", "sortBy": "vv", "period": "30", "maxItems": 10, "includeDetailedVideoData": false, "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("socialdataapi/tiktok-trending-videos-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 = { "videoUrls": [], "countryCode": "US", "sortBy": "vv", "period": "30", "maxItems": 10, "includeDetailedVideoData": False, "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("socialdataapi/tiktok-trending-videos-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 '{ "videoUrls": [], "countryCode": "US", "sortBy": "vv", "period": "30", "maxItems": 10, "includeDetailedVideoData": false, "proxyConfiguration": { "useApifyProxy": true } }' | apify call socialdataapi/tiktok-trending-videos-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,socialdataapi/tiktok-trending-videos-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/q0xWB2hGtULzyvs2R/builds/8sVi0oEwFWzeoqh27/openapi.json