# YouTube Trending Topic Finder (`coregent/youtube-trending-topic-finder`) Actor Discover rising YouTube topics in any niche. Analyzes recent videos and Shorts by view velocity, engagement, upload age and creator diversity, clusters repeated themes, and returns ranked trending topics with momentum scores, signals and evidence videos. - **URL**: https://apify.com/coregent/youtube-trending-topic-finder.md - **Developed by:** [Delowar Munna](https://apify.com/coregent) (community) - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $3.00 / 1,000 trending topic results 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/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 ## YouTube Trending Topic Finder — Rising Topics, Momentum & Content Opportunities ![YouTube Trending Topic Finder](https://github.com/coregentdevspace/youtube-trending-topic-finder-assets/blob/main/thumbnail-youtube-trending-topic-finder.png?raw=true) **Find out what is gaining traction on YouTube in any niche — as topics, not just a list of popular videos.** Give the Actor a niche such as `artificial intelligence`, `fitness` or `personal finance`. It samples recent YouTube videos and Shorts, measures how fast each one is gathering views and engagement since upload, spots breakout videos, groups repeated themes across different creators, and returns **one ranked row per trending topic** with a momentum score, a tier, plain-English reasons and the evidence videos behind it. **No YouTube login. No browser. Results in seconds to minutes.** *** ### ⚡ Quick start 1. Type a niche into **Seed topics**. 2. Leave the **Time window** at `Last 7 days`. 3. Click **Start**. ```json { "seedTopics": ["artificial intelligence"], "regionCode": "US", "languageCode": "en", "timeWindow": "7_DAYS", "videosPerSeed": 250, "maxTopics": 25 } ``` You get rows like *"AI Agents — BREAKOUT: 8 of 13 videos from the last 7 days are gaining traction, from 8 creators, with 2 videos well above the niche's typical view velocity; most of the activity is Shorts"*, each with the videos that prove it. *** ### What counts as a trending topic? A theme — a name, product, phrase or hashtag — that shows up across **several recent videos from several different creators**, and whose videos are gathering views **faster than is typical for the niche right now**. A topic scores highly when these line up: - recent uploads, not old classics - high views **per hour since upload** - strong engagement (likes + comments) per hour - the same theme repeated across videos - multiple independent creators - activity clustered in the most recent part of the window ### How is this different from a "trending videos" scraper? | | Trending-videos scrapers | YouTube search scrapers | **This Actor** | | ------------------------------------------- | ---------------------------------- | --------------------------- | ------------------------------------ | | One row is | a video | a video | **a topic** | | Ranked by | position on a chart | relevance or lifetime views | **momentum since upload** | | Works for a specific niche | ❌ only YouTube's broad categories | ✅ | ✅ | | Tells you *what theme* is rising | ❌ | ❌ | ✅ | | Separates one viral video from a real trend | ❌ | ❌ | ✅ needs several videos and creators | | Explains why | ❌ | ❌ | ✅ signals + one-line summary | ### Does YouTube still have a generic Trending page? Not as a useful foundation. YouTube's old single Trending list has given way to category hubs, charts, search, recommendations and Shorts feeds. Those are too broad to tell you what is rising **inside your niche**. This Actor builds its own sample from recent search results for each seed instead. ### Does the Actor use lifetime views? No. A video's views are always divided by its age in hours — a video with 100,000 views after 10 hours outranks one with 1,000,000 views after 3 months. Only videos uploaded inside your time window are analysed at all. ### What is view velocity? `views ÷ hours since upload` (minimum one hour). Each video's velocity is then ranked against the other videos in the same niche and format, so a fitness Short is compared with other fitness Shorts, not with long-form AI explainers. A **breakout video** is one in roughly the top 15% of its niche for velocity and at least 1.5× the niche's median — or an above-median video pulling unusually many views for its channel's size, or unusually much engagement per hour. A video **has traction** when it is a breakout, or is at least as fast as its niche's median and has at least 100 views. Brand-new uploads nobody has watched yet still count towards a topic's video count, but not towards its tier. ### What do BREAKOUT, RISING, ACTIVE and WEAK mean? | Tier | Meaning | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | **BREAKOUT** | Score ≥ 70, at least 2 breakout videos, and videos with traction from at least 3 creators — strong recent acceleration across the niche | | **RISING** | Score ≥ 50 — clearly positive momentum with enough evidence | | **ACTIVE** | Score ≥ 30 — current activity, acceleration unclear | | **WEAK** | Below 30 — little evidence or momentum | Whatever the score, a topic is WEAK unless **at least 2 of its videos, from at least 2 creators, have traction** — one viral video surrounded by unwatched uploads is not a trend. By default, BREAKOUT, RISING and ACTIVE topics are returned. Set **Minimum trend tier** to change that. Each topic also carries a **confidence** of HIGH, MEDIUM or LOW, based on how many videos with traction and how many creators support it, how complete the metadata is, and how tightly its videos share the theme. ### How is the trend score calculated? 0–100, from six parts (each topic's `scoreBreakdown` shows the points it earned): | Component | Max points | | ------------------------------------------------------------------------------------------ | ---------- | | View velocity (median velocity rank of the topic's videos, so one outlier cannot carry it) | 30 | | Breakout videos (3 or more = full points) | 20 | | Creator diversity (creators with a video that has traction) | 15 | | Recency (share of videos in the newest third of the window) | 15 | | Engagement velocity | 10 | | Video count (videos with traction) | 10 | Penalties: **−15** when one channel makes 60%+ of the topic's videos, **−20** when most of the topic's views sit on its oldest videos with almost nothing recent, **−15** when only 3 videos support it. If like and comment counts are not available, the engagement part is dropped and the rest scaled up to 100. Every row also lists `trendSignals` such as `HIGH_VIEW_VELOCITY`, `MULTIPLE_BREAKOUT_VIDEOS`, `MULTIPLE_CREATORS`, `RECENT_UPLOAD_CLUSTER`, `RISING_SHORTS_ACTIVITY`, `CROSS_SEED_OCCURRENCE`, and weakening signals such as `SINGLE_VIDEO_DRIVEN`, `LOW_TRACTION`, `SINGLE_CREATOR_DOMINANCE`, `LOW_SAMPLE_SIZE` or `LOW_RECENCY` — so you never get just a number. ### Why require several videos and creators? Because one viral video is not a trend, and one prolific channel posting the same theme five times is not one either. By default a topic needs **3 videos from 2 different creators**; both are adjustable. On top of that, a topic only rises above WEAK when at least 2 of those videos, from 2 different creators, actually have traction. ### How many videos are analysed? **Videos sampled per seed** (default 250, up to 500) recent search results per seed, split across the content types you pick. Duplicates found by several seeds are analysed once. Videos outside the exact time window are dropped after their upload time is checked. 💡 The default 250 videos per seed usually finds 10–15 topics in a single niche; 100 gives a quicker but thinner read, and **500 finds more and smaller topics**. The run summary reports how many videos were collected, analysed and dropped, and why. ### Are Shorts included? Yes — by default the sample is half long-form videos and half Shorts. Shorts come from YouTube's own Shorts search filter, so they are real Shorts; Shorts older than the window are dropped once their exact upload time is checked. Shorts are ranked against other Shorts (they collect views much faster), and each topic reports `shortsCount`, `shortsShare` and a `RISING_SHORTS_ACTIVITY` signal when Shorts are driving it. Live streams are available as a third content type. ### Can I choose country and language? Yes. **Country** (any two-letter code — `US`, `GB`, `AU`, `IN`, `BD`, …) localises YouTube search, and **Language** sets the interface language. Country changes which videos search surfaces; it does **not** prove where the viewers are. Topic extraction is tuned for English titles; other languages work but may let through more filler phrases. ### What does seed expansion do? With **Expand seeds** on, each seed is widened with YouTube's own autocomplete — `AI tools` → `AI tools for students`, `AI tools for video editing`, `AI tools to make money` — and every suggestion is sampled and analysed together with the seed. Each suggestion samples a quarter of *Videos sampled per seed* (at least 20), so expansion widens coverage at the cost of a longer run. ### Is AI required? No. Topics come from statistics and rules: phrase extraction from titles, hashtags and descriptions, clustering of phrases that describe the same videos, and the velocity metrics above. No language model is called and no AI cost is involved. ### Are transcripts or comments used? No. Only public video metadata is used — title, description, hashtags, upload time, views, likes, comment count, duration and channel. Comment *text* and transcripts are not read. ### How does pricing work? Pay per result: you are charged once for each **topic row** delivered to your dataset. Videos sampled, searches made and topics filtered out are not charged, and a run that finds no topics writes one free explanatory row instead. **Max topics returned** caps the cost of any run, and the Actor stops cleanly at your run's spending limit. See the **Pricing** tab for current rates — this README deliberately doesn't quote figures, as they can change. ### Can I schedule recurring scans? Yes. Save your input as an Apify **Task** and attach a **Schedule** (for example, every morning for `24 hours`, or weekly for `7 days`). Each run is a fresh snapshot, so comparing runs shows which topics are holding, climbing or fading. ### Can I use the API or MCP? Yes — like any Apify Actor, it runs from the Apify API, the JavaScript and Python clients, integrations (Make, Zapier, n8n) and Apify's MCP server for AI agents. ```bash curl "https://api.apify.com/v2/acts/coregent~youtube-trending-topic-finder/run-sync-get-dataset-items?token=" \ -X POST -H "Content-Type: application/json" \ -d '{"seedTopics": ["artificial intelligence"], "timeWindow": "7_DAYS"}' ``` *** ### Input examples #### Several niches, one country ```json { "seedTopics": ["artificial intelligence", "robotics", "productivity"], "regionCode": "AU", "timeWindow": "7_DAYS", "videosPerSeed": 150, "minimumVideosPerTopic": 3, "minimumCreatorsPerTopic": 2, "maxTopics": 50 } ``` #### Seed expansion ```json { "seedTopics": ["AI tools"], "expandSeeds": true, "maxExpandedSeedsPerTopic": 10, "regionCode": "US", "languageCode": "en", "timeWindow": "14_DAYS", "videosPerSeed": 100 } ``` #### Shorts only ```json { "seedTopics": ["fitness"], "contentTypes": ["SHORTS"], "timeWindow": "7_DAYS", "videosPerSeed": 250, "minimumTrendTier": "RISING" } ``` ### Input reference | Field | Default | What it does | | -------------------------- | ------------------ | ----------------------------------------------------------------------- | | `seedTopics` | — (required) | Niches or keywords, up to 25 | | `timeWindow` | `7_DAYS` | `24_HOURS`, `3_DAYS`, `7_DAYS`, `14_DAYS`, `30_DAYS`, `90_DAYS` | | `videosPerSeed` | `250` | Recent videos sampled per seed (10–500) | | `contentTypes` | `VIDEOS`, `SHORTS` | Any of `VIDEOS`, `SHORTS`, `LIVE` | | `regionCode` | `US` | Two-letter country code for search localisation | | `languageCode` | `en` | Interface language | | `expandSeeds` | `false` | Add YouTube autocomplete suggestions as extra queries | | `maxExpandedSeedsPerTopic` | `10` | Suggestions per seed when expanding | | `minimumVideosPerTopic` | `3` | Evidence videos a topic needs | | `minimumCreatorsPerTopic` | `2` | Distinct channels a topic needs | | `minimumTrendTier` | `ACTIVE` | Lowest tier returned | | `maxTopics` | `50` | Topics returned at most (caps cost) | | `minimumViews` | `0` | Drop videos below this view count | | `minimumEngagement` | `0` | Drop videos below this many likes + comments (where shown) | | `includeEvidenceVideos` | `true` | Attach supporting videos to each topic | | `maxEvidenceVideos` | `5` | Evidence videos per topic | | `includeChannelContext` | `true` | Add channel subscriber counts; enables small-channel breakout detection | | `maxConcurrency` | `5` | Seeds searched in parallel | | `maxRetries` | `3` | Retries on rate-limit or server errors | | `proxyConfiguration` | no proxy | Optional — see the proxy policy below | *** ### Output One dataset row per topic, highest score first. The samples below are one real row ("AI Agents", rank 5 of 18) from a default run on `artificial intelligence`, shown as each dataset view presents it. ![Trending Topics table view: ranked topics with tier, score, confidence, video and creator counts, velocity and summary](https://github.com/coregentdevspace/youtube-trending-topic-finder-assets/blob/main/youtube-trending-topic-finder-output-trending-topics-table-view.png?raw=true) #### Trending Topics The ranked table: one line per topic with its tier, score and the one-sentence reason. ```json { "rank": 5, "topic": "AI Agents", "trendTier": "BREAKOUT", "trendScore": 72, "confidence": "HIGH", "videoCount": 13, "uniqueCreators": 13, "avgViewsPerHour": 535, "breakoutVideoCount": 2, "shortsShare": 0.846, "trendSummary": "AI Agents is breaking out: 8 of 13 videos from the last 7 days are gaining traction, from 8 creators, with 2 videos well above the niche's typical view velocity; most of the activity is Shorts." } ``` #### Signals & Creators Why the topic ranks where it does, which phrases belong to it, and who is making it (creators shortened to two of five). ```json { "rank": 5, "topic": "AI Agents", "trendTier": "BREAKOUT", "trendSignals": [ "MULTIPLE_BREAKOUT_VIDEOS", "MULTIPLE_CREATORS", "RECENT_UPLOAD_CLUSTER", "REPEATED_TITLE_THEME", "REPEATED_KEYPHRASE" ], "relatedPhrases": ["#aisafety", "#aiagents"], "seedTopics": ["artificial intelligence"], "topCreators": [ { "channelId": "UCOFl0wDeBMSBbK3jNJQHHFg", "channelName": "AI Copium", "channelUrl": "https://www.youtube.com/channel/UCOFl0wDeBMSBbK3jNJQHHFg", "videosInTopic": 1, "subscriberCount": 34200 }, { "channelId": "UCSSB338C8A9ZOXtsbfM7phg", "channelName": "Mikey Website", "channelUrl": "https://www.youtube.com/channel/UCSSB338C8A9ZOXtsbfM7phg", "videosInTopic": 1, "subscriberCount": 41900 } ], "observedWindow": { "requested": "7_DAYS", "oldestEvidenceAt": "2026-10-15T14:15:33.000Z", "newestEvidenceAt": "2026-10-20T23:00:14.000Z" } } ``` #### Evidence Videos The videos behind the topic, best first (shortened to two of five). ```json { "rank": 5, "topic": "AI Agents", "trendTier": "BREAKOUT", "evidenceVideos": [ { "videoId": "rb4CTZjHCNg", "title": "Researchers Made “First Contact” With Rogue AI Agents…", "url": "https://www.youtube.com/watch?v=rb4CTZjHCNg", "channelId": "UCOFl0wDeBMSBbK3jNJQHHFg", "channelName": "AI Copium", "contentType": "VIDEO", "publishedAt": "2026-10-16T14:15:28.000Z", "timestampPrecision": "exact", "views": 648099, "likes": 7034, "comments": 1356, "viewsPerHour": 5917, "engagementRate": 0.0129, "subscriberCount": 34200, "viewsToSubscribers": 18.95, "isBreakoutVideo": true }, { "videoId": "TiNUHdbfOFs", "title": "AI Can Self-Replicate Now... #anthropic #aisafety #ai", "url": "https://www.youtube.com/watch?v=TiNUHdbfOFs", "channelId": "UCkVfrGwV-iG9bSsgCbrNPxQ", "channelName": "Better Stack", "contentType": "SHORT", "publishedAt": "2026-10-18T20:00:23.000Z", "timestampPrecision": "exact", "views": 17584, "likes": 796, "comments": 85, "viewsPerHour": 315.2, "engagementRate": 0.0501, "subscriberCount": 235000, "viewsToSubscribers": 0.075, "isBreakoutVideo": true } ] } ``` #### All Fields The complete row, including the per-topic `metrics` and the points behind the score in `scoreBreakdown` (creators and evidence videos shortened to two). ```json { "rowType": "trending_topic", "rank": 5, "topic": "AI Agents", "seedTopics": ["artificial intelligence"], "relatedPhrases": ["#aisafety", "#aiagents"], "trendScore": 72, "trendTier": "BREAKOUT", "confidence": "HIGH", "trendSignals": [ "MULTIPLE_BREAKOUT_VIDEOS", "MULTIPLE_CREATORS", "RECENT_UPLOAD_CLUSTER", "REPEATED_TITLE_THEME", "REPEATED_KEYPHRASE" ], "trendSummary": "AI Agents is breaking out: 8 of 13 videos from the last 7 days are gaining traction, from 8 creators, with 2 videos well above the niche's typical view velocity; most of the activity is Shorts.", "videoCount": 13, "uniqueCreators": 13, "topCreatorShare": 0.077, "totalViews": 704933, "avgViewsPerHour": 535, "breakoutVideoCount": 2, "shortsShare": 0.846, "metrics": { "videoCount": 13, "uniqueCreators": 13, "topCreatorShare": 0.077, "totalViews": 704933, "avgViews": 54226, "medianViews": 258, "avgViewsPerHour": 535, "medianViewsPerHour": 38.6, "totalLikes": 7976, "totalComments": 1467, "avgEngagementRate": 0.0111, "avgEngagementPerHour": 7.7, "breakoutVideoCount": 2, "tractionVideoCount": 8, "tractionCreators": 8, "shortsCount": 11, "longFormCount": 2, "liveCount": 0, "shortsShare": 0.846, "avgSubscriberCount": 454368 }, "scoreBreakdown": { "viewVelocity": 14.8, "breakoutVideos": 13.3, "creatorDiversity": 15, "recency": 15, "engagementVelocity": 3.8, "videoCount": 10, "penalties": {}, "engagementDataAvailable": true }, "observedWindow": { "requested": "7_DAYS", "oldestEvidenceAt": "2026-10-15T14:15:33.000Z", "newestEvidenceAt": "2026-10-20T23:00:14.000Z" }, "topCreators": [ { "channelId": "UCOFl0wDeBMSBbK3jNJQHHFg", "channelName": "AI Copium", "channelUrl": "https://www.youtube.com/channel/UCOFl0wDeBMSBbK3jNJQHHFg", "videosInTopic": 1, "subscriberCount": 34200 }, { "channelId": "UCSSB338C8A9ZOXtsbfM7phg", "channelName": "Mikey Website", "channelUrl": "https://www.youtube.com/channel/UCSSB338C8A9ZOXtsbfM7phg", "videosInTopic": 1, "subscriberCount": 41900 } ], "evidenceVideos": [ { "videoId": "rb4CTZjHCNg", "title": "Researchers Made “First Contact” With Rogue AI Agents…", "url": "https://www.youtube.com/watch?v=rb4CTZjHCNg", "channelId": "UCOFl0wDeBMSBbK3jNJQHHFg", "channelName": "AI Copium", "contentType": "VIDEO", "publishedAt": "2026-10-16T14:15:28.000Z", "timestampPrecision": "exact", "views": 648099, "likes": 7034, "comments": 1356, "viewsPerHour": 5917, "engagementRate": 0.0129, "subscriberCount": 34200, "viewsToSubscribers": 18.95, "isBreakoutVideo": true }, { "videoId": "TiNUHdbfOFs", "title": "AI Can Self-Replicate Now... #anthropic #aisafety #ai", "url": "https://www.youtube.com/watch?v=TiNUHdbfOFs", "channelId": "UCkVfrGwV-iG9bSsgCbrNPxQ", "channelName": "Better Stack", "contentType": "SHORT", "publishedAt": "2026-10-18T20:00:23.000Z", "timestampPrecision": "exact", "views": 17584, "likes": 796, "comments": 85, "viewsPerHour": 315.2, "engagementRate": 0.0501, "subscriberCount": 235000, "viewsToSubscribers": 0.075, "isBreakoutVideo": true } ], "regionCode": "US", "languageCode": "en", "scrapedAt": "2026-10-21T03:47:20.778Z" } ``` Missing values are `null`, never `0` — a video with hidden likes does not look like a flop. **Run summary:** the key-value store record `RUN_SUMMARY` reports seeds, expanded queries, videos collected / analysed / dropped (and why), duplicates removed, field availability (exact timestamps, views, likes, comments, subscriber counts), breakout videos, topics by tier, a status per seed, and request counts. If a seed fails, `RETRY_INPUT` holds a ready-made input that re-runs just the failed seeds. **Statuses:** a failed seed never fails the run. Per-seed status is one of `SUCCESS`, `PARTIAL_RESULT`, `NO_RESULTS`, `INVALID_SEED`, `SEARCH_FAILED`, `RATE_LIMITED` or `BLOCKED`. A run that delivers no topics writes one free `run_status` row explaining why and what to change. *** ### Tips - **Too few topics?** Raise *Videos sampled per seed* to 500, lengthen the window, or turn on seed expansion. - **Too broad?** Use a narrower seed (`kettlebell training` rather than `fitness`) — topics are always subtopics of the seed, never the seed restated. - **Creator-content ideas:** filter to `RISING` and above, then open the evidence videos for hooks and angles. - **Shorts trends:** set *Content types* to Shorts only with a 3–7 day window. ### 🚦 Proxy policy No proxy is needed for normal runs — the Actor reads public YouTube endpoints at a conservative pace. Use **Apify Datacenter** proxy only if a run is being rate-limited. **Apify Residential proxy is not supported.** The Actor fails at startup if `apifyProxyGroups` includes `RESIDENTIAL`. Reason: in pay-per-event Actors, residential bandwidth is billed to the developer, not the run user, so a bandwidth-heavy run could exceed the per-result revenue. If you genuinely need residential routing, supply your own provider via the proxy editor's **Custom proxy URLs** field — that traffic goes through your provider, not Apify: ``` http://user:pass@proxy.iproyal.com:12321 http://user:pass@proxy.brightdata.com:22225 http://user:pass@proxy.oxylabs.io:7777 ``` ### Limitations - Topics are detected from a **sample** of recent public videos per seed, not from all of YouTube. - View, like and comment counts change constantly; each run is a snapshot. - Search localisation by country does not prove where viewers are. - Topic labels are extracted phrases, so occasionally a broad word or hashtag surfaces as a topic; the signals and evidence videos show how much weight to give it. - Videos whose upload time cannot be determined are left out rather than guessed. ### Disclaimer This is an unofficial tool and is not affiliated with, endorsed by or sponsored by YouTube or Google. Trend scores, tiers and signals are analytics derived by this Actor from public video metadata — they are not official YouTube metrics, not search volume, and not a guarantee of future views. You are responsible for how you use the output. # Actor input Schema ## `seedTopics` (type: `array`): Niches or keywords to analyse — one per line. For each seed the Actor samples recent YouTube videos and finds the **subtopics** gaining traction inside it. Examples: `artificial intelligence`, `home workout`, `personal finance`, `gaming laptops`. 💡 **TIP:** a broad niche (`fitness`) surfaces the big themes; a narrower one (`kettlebell training`) surfaces specific angles. Up to 25 seeds per run. ## `timeWindow` (type: `string`): Only videos uploaded within this window are analysed. Trending is measured as momentum **inside** the window — views per hour since upload — never lifetime views. 💡 Use `24 hours`–`7 days` for news-like niches, `14`–`30 days` for slower ones. ## `videosPerSeed` (type: `integer`): How many recent videos to sample for each seed. More videos find more (and smaller) topics, at the cost of a longer run. Typical values: `50`–`100` for a quick look, `250` (default), `500` for a thorough scan. ## `contentTypes` (type: `array`): Which formats to analyse. Shorts and long-form are ranked separately (Shorts naturally collect views faster), then combined into topics. - **Videos** — regular long-form uploads - **Shorts** — short-form videos up to 3 minutes - **Live** — live streams and their replays ## `regionCode` (type: `string`): Two-letter country code YouTube search is localised to, e.g. `US`, `GB`, `AU`, `CA`, `IN`, `BD`. This biases which videos search returns — it does not prove where viewers are. ## `languageCode` (type: `string`): Interface language for search and suggestions, e.g. `en`, `es`, `pt`, `de`, `hi`. Topic extraction is tuned for English; other languages work but may surface more filler phrases. ## `expandSeeds` (type: `boolean`): Also analyse what people type after your seed in YouTube search — e.g. `AI tools` → `AI tools for students`, `AI tools for video editing`. Each suggestion samples a quarter of *Videos sampled per seed* (at least 20), so expansion widens coverage and adds run time. ## `maxExpandedSeedsPerTopic` (type: `integer`): How many autocomplete suggestions to analyse for each seed. Only used when expansion is on. ## `minimumVideosPerTopic` (type: `integer`): A theme must appear in at least this many recent videos to count as a topic. One viral video is not a trend. ## `minimumCreatorsPerTopic` (type: `integer`): A theme must come from at least this many different channels. Stops one prolific channel from looking like a trend. ## `minimumTrendTier` (type: `string`): Return only topics at or above this tier. - **Breakout** — strong recent acceleration across several creators - **Rising** — clearly positive momentum - **Active** — current activity, acceleration unclear - **Weak** — little evidence or momentum ## `maxTopics` (type: `integer`): The highest-scoring topics up to this number are returned. You pay per topic returned, so this caps the cost of a run. ## `minimumViews` (type: `integer`): Ignore videos below this view count before analysis. `0` keeps everything. ## `minimumEngagement` (type: `integer`): Ignore videos with fewer likes + comments than this. Applied only where YouTube shows like/comment counts — videos with hidden counts are kept. `0` keeps everything. ## `includeEvidenceVideos` (type: `boolean`): Attach the videos that most strongly support each topic — title, link, channel, views, likes, comments, views/hour and breakout flag. ## `maxEvidenceVideos` (type: `integer`): How many evidence videos to attach to each topic, strongest momentum first. ## `includeChannelContext` (type: `boolean`): Look up subscriber counts for the channels in each topic. Adds subscriber numbers to creators and evidence videos, and lets small-channel breakouts (views far above subscriber count) count as breakouts. ## `maxConcurrency` (type: `integer`): How many seeds to search at once. Higher is faster on large runs; lower is gentler on YouTube. ## `maxRetries` (type: `integer`): How many times to retry a request that fails with a rate-limit (429) or server (5xx) error, with exponential backoff. ## `proxyConfiguration` (type: `object`): Optional. The Actor runs without a proxy by default. Apify Datacenter proxy and your own proxy URLs are supported; Apify Residential proxy is not. ## Actor input object example ```json { "seedTopics": [ "artificial intelligence" ], "timeWindow": "7_DAYS", "videosPerSeed": 250, "contentTypes": [ "VIDEOS", "SHORTS" ], "regionCode": "US", "languageCode": "en", "expandSeeds": false, "maxExpandedSeedsPerTopic": 10, "minimumVideosPerTopic": 3, "minimumCreatorsPerTopic": 2, "minimumTrendTier": "ACTIVE", "maxTopics": 50, "minimumViews": 0, "minimumEngagement": 0, "includeEvidenceVideos": true, "maxEvidenceVideos": 5, "includeChannelContext": true, "maxConcurrency": 5, "maxRetries": 3, "proxyConfiguration": { "useApifyProxy": false } } ``` # Actor output Schema ## `overview` (type: `string`): No description ## `evidence` (type: `string`): No description ## `runSummary` (type: `string`): No description # 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 = { "seedTopics": [ "artificial intelligence" ], "contentTypes": [ "VIDEOS", "SHORTS" ], "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("coregent/youtube-trending-topic-finder").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 = { "seedTopics": ["artificial intelligence"], "contentTypes": [ "VIDEOS", "SHORTS", ], "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("coregent/youtube-trending-topic-finder").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 '{ "seedTopics": [ "artificial intelligence" ], "contentTypes": [ "VIDEOS", "SHORTS" ], "proxyConfiguration": { "useApifyProxy": false } }' | apify call coregent/youtube-trending-topic-finder --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,coregent/youtube-trending-topic-finder" } } } ``` 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/58NTAYLLjhOr36M17/builds/bTKMjSpih5k31crk7/openapi.json