# YouTube Trending Videos Scraper (`khadinakbar/youtube-trending-videos-scraper`) Actor Scrape YouTube's official country-level Trending Music and Trending Movie Trailer charts. Use it for regional content research, not search or recommendations. Returns ranked videos with IDs, URLs, channels, artists, release dates, thumbnails, and chart context. Charged per scan and video. - **URL**: https://apify.com/khadinakbar/youtube-trending-videos-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Videos, Social media, MCP servers - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.60 / 1,000 trending video returneds 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## YouTube Trending Videos Scraper Get ranked videos from YouTube's official, non-personalized Trending Charts by country. This actor returns a compact, structured snapshot of either **Trending Music Videos** or **Trending Movie Trailers**: rank, video and channel IDs, canonical YouTube URL, artists, duration, release date, thumbnail, and chart context. Use it for repeatable regional trend monitoring, editorial planning, music and trailer research, or creator-market analysis. Do not use it for YouTube search results, personalized Home recommendations, a channel's popular uploads, YouTube Studio audience insights, or a broad legacy Trending feed. Those are different YouTube surfaces and are deliberately not substituted here. ### What it extracts Every dataset item has the same flat, agent-friendly shape. | Field | Meaning | | ------------------------------------------------------ | ------------------------------------------------ | | `rank` | Current position in the requested Trending Chart | | `videoId`, `videoUrl` | Stable YouTube video ID and canonical watch URL | | `title` | Video title supplied by YouTube Charts | | `channelId`, `channelName` | Associated channel when YouTube supplies it | | `artists` | Chart artist credits in display order | | `durationSeconds`, `releaseDate` | Video duration and release date when available | | `thumbnailUrl` | Largest chart-provided thumbnail | | `previousRank`, `viewsChangePercent`, `periodsOnChart` | Movement data when YouTube provides it | | `region`, `chart`, `sourceUrl`, `scrapedAt` | Exact chart context and collection time | The actor also writes `OUTPUT` and `RUN_SUMMARY` in the default key-value store. They contain the terminal outcome, result count, completed countries, any source failures, and PPE event counters. ### When to use it Use this actor when your question is one of these: - What music videos are gaining the most traction in the United States today? - Which movie trailers are trending in the United Kingdom this week? - How do official Trending Music rankings differ across the US, Canada, and Australia? - Which entries gained or lost rank between scheduled chart snapshots? Charts are non-personalized: viewers in the same country see the same ranking. YouTube updates these chart views roughly every 30 minutes, so scheduling a recurring Actor task is the right way to build a time series. ### Input All inputs have useful defaults; no input is required for a US Trending Music snapshot. | Input | Default | Notes | | --------------------- | --------------- | --------------------------------------------------------------------- | | `regions` | `["US"]` | One to ten ISO alpha-2 country codes, for example `US`, `GB`, or `PK` | | `chart` | `trendingMusic` | `trendingMusic` or `trendingMovieTrailers` | | `maxResultsPerRegion` | `30` | Keep from 1 to 30 ranked entries for each country | | `language` | `en` | BCP 47 UI language tag such as `en`, `es`, or `pt-BR` | #### Example input ```json { "regions": ["US", "GB"], "chart": "trendingMusic", "maxResultsPerRegion": 10, "language": "en" } ```` For movie trailers, set `chart` to `trendingMovieTrailers`. YouTube does not publish every chart in every ISO country; an unavailable country/category pair is a valid empty result, not silently replaced with unrelated content. ### Output example ```json { "rank": 1, "videoId": "ESORouDblNg", "videoUrl": "https://www.youtube.com/watch?v=ESORouDblNg", "title": "One Two", "channelId": "UC1_liDR4fRFJgH4HoJeV8cw", "channelName": "Future - Topic", "artists": ["Future"], "durationSeconds": 120, "releaseDate": "2026-07-09", "thumbnailUrl": "https://i.ytimg.com/vi/ESORouDblNg/maxresdefault.jpg", "previousRank": null, "viewsChangePercent": null, "periodsOnChart": null, "isAvailable": true, "region": "US", "chart": "trendingMusic", "sourceUrl": "https://charts.youtube.com/charts/TrendingVideos/us", "scrapedAt": "2026-07-14T12:30:00.000Z" } ``` Fields unavailable from a particular YouTube chart are returned as `null`, never omitted. This keeps scheduled exports stable for spreadsheets, databases, and AI agents. ### Pricing This is a **Pay per event + usage** actor. Platform compute usage is passed through in addition to the predictable event charges. | Event | Price | When charged | | ----------------------- | -------: | --------------------------------------------------------- | | Actor start | $0.00005 | Once when a run starts | | Trending chart scanned | $0.03 | After a requested country chart is successfully retrieved | | Trending video returned | $0.0006 | For each validated video written to the dataset | A one-country, 30-video run costs about **$0.04805 plus platform usage**. A one-country top-ten snapshot costs about **$0.03605 plus platform usage**. Empty, valid chart responses do not generate per-video charges. ### API examples #### JavaScript ```js const response = await fetch( 'https://api.apify.com/v2/acts/khadinakbar~youtube-trending-videos-scraper/runs?token=YOUR_APIFY_TOKEN', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ regions: ['US'], chart: 'trendingMovieTrailers', maxResultsPerRegion: 10, language: 'en', }), }, ); console.log(await response.json()); ``` #### Python ```python import requests response = requests.post( 'https://api.apify.com/v2/acts/khadinakbar~youtube-trending-videos-scraper/runs', params={'token': 'YOUR_APIFY_TOKEN'}, json={ 'regions': ['US', 'CA'], 'chart': 'trendingMusic', 'maxResultsPerRegion': 20, 'language': 'en', }, timeout=60, ) print(response.json()) ``` Use your Apify token as a secret. Do not put a token in the actor input, dataset, or a public task. ### Reliability and limits The actor calls YouTube's public Charts browse service directly. It uses retries for transient source failures and reports `PARTIAL` when at least one country produces useful data while another fails. It reports `VALID_EMPTY` when YouTube truthfully has no entries for a valid chart/country request. Invalid country codes, invalid chart types, and out-of-range limits return `INVALID_INPUT` with a clear correction. The actor does not use a user login, cookies, a YouTube Data API key, proxy configuration, or a fallback to search. That last point matters: search popularity is not the same as a YouTube Trending Chart. If the public chart contract changes or cannot return useful data for any country, the run fails honestly with `UPSTREAM_FAILED` rather than returning unrelated videos. ### Related YouTube actors Use a dedicated actor when the data goal is not a public Trending Chart: - [YouTube Search Scraper](https://apify.com/khadinakbar/youtube-search-scraper) for keyword search results - [YouTube Comments Scraper](https://apify.com/khadinakbar/youtube-comments-scraper) for video discussions - [YouTube Transcript Extractor](https://apify.com/khadinakbar/youtube-transcript-extractor) for subtitles and transcripts - [YouTube Channel Scraper](https://apify.com/khadinakbar/youtube-channel-scraper) for channel profiles - [YouTube Channel Videos Scraper](https://apify.com/khadinakbar/youtube-channel-videos-scraper) for channel uploads - [YouTube Shorts Scraper](https://apify.com/khadinakbar/youtube-shorts-scraper) for short-form videos - [YouTube Community Posts Scraper](https://apify.com/khadinakbar/youtube-community-posts-scraper) for community updates - [YouTube Video Downloader](https://apify.com/khadinakbar/youtube-video-downloader) for media downloads ### FAQ #### How many results can I scrape with YouTube Trending Videos Scraper? You can request up to 30 currently available entries per country chart and up to ten countries per run. Schedule recurring runs to retain historical rank snapshots in Apify datasets. #### Can I integrate YouTube Trending Videos Scraper with other apps? Yes. The default dataset can be exported as JSON, CSV, Excel, RSS, or via the Apify API, then forwarded to automation tools, warehouses, or a dashboard. #### Can I use YouTube Trending Videos Scraper with the Apify API? Yes. Start a run with the Apify API and read its default dataset after completion. The JavaScript and Python examples above show the input shape. #### Does it return YouTube's old general Trending page? No. YouTube's current public non-personalized trending surfaces are category-specific Charts. This actor returns official Trending Music Videos and Trending Movie Trailers and labels the source precisely. #### Can I use it for personalized recommendations or YouTube Studio Trends? No. Those products depend on viewer or channel-specific signals and are outside this public, repeatable chart contract. ### Legal and compliance Use this actor only for lawful purposes and in accordance with the policies that apply to your use. The actor collects public chart information and does not access private accounts, bypass authentication, or obtain non-public YouTube analytics. ### Your feedback If this actor saves your team time, please leave feedback in its Apify Console issue tab. Clear reports with the country, chart, run ID, and expected result help keep the public-chart contract reliable. # Actor input Schema ## `regions` (type: `array`): Use this when you need the same official trending chart for one or more countries. Enter ISO 3166-1 alpha-2 codes such as 'US', 'GB', or 'PK'; for example, \["US", "GB"]. Defaults to \["US"] and accepts at most 10 countries per run. This is a country selector, not a language or city filter. ## `chart` (type: `string`): Use this when you need a specific official YouTube Trending Chart. Choose 'trendingMusic' for Trending Music Videos or 'trendingMovieTrailers' for Trending Movie Trailers. Defaults to 'trendingMusic', which is the broader of the two public trending charts. This is not a generic YouTube search, Home feed, Gaming Explore feed, or personalized recommendation list. ## `maxResultsPerRegion` (type: `integer`): Use this when you need to cap the number of ranked videos kept from each country chart. Enter an integer from 1 to 30; for example, 10 returns the top ten available entries per country. Defaults to 30, the current public chart maximum. This is a per-country result cap, not a page count or a global total. ## `language` (type: `string`): Use this when you want YouTube's chart labels requested in a particular language. Enter a BCP 47 language tag such as 'en', 'es', or 'pt-BR'. Defaults to 'en'; titles and creator names remain exactly as supplied by YouTube. This changes chart interface localization only, not the chart's country ranking. ## Actor input object example ```json { "regions": [ "US" ], "chart": "trendingMusic", "maxResultsPerRegion": 30, "language": "en" } ``` # Actor output Schema ## `results` (type: `string`): One normalized record for every returned YouTube Trending Chart entry. ## `output` (type: `string`): Terminal outcome and concise run summary. ## `runSummary` (type: `string`): Counts, completed countries, warnings, and billing counters for this run. # 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 = { "regions": [ "US" ], "chart": "trendingMusic", "maxResultsPerRegion": 30, "language": "en" }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/youtube-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 = { "regions": ["US"], "chart": "trendingMusic", "maxResultsPerRegion": 30, "language": "en", } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/youtube-trending-videos-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 '{ "regions": [ "US" ], "chart": "trendingMusic", "maxResultsPerRegion": 30, "language": "en" }' | apify call khadinakbar/youtube-trending-videos-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/youtube-trending-videos-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Trending Videos Scraper", "description": "Scrape YouTube's official country-level Trending Music and Trending Movie Trailer charts. Use it for regional content research, not search or recommendations. Returns ranked videos with IDs, URLs, channels, artists, release dates, thumbnails, and chart context. Charged per scan and video.", "version": "1.0", "x-build-id": "rCJ3WsE9hPsiq8lDK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~youtube-trending-videos-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-youtube-trending-videos-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/khadinakbar~youtube-trending-videos-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-youtube-trending-videos-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/khadinakbar~youtube-trending-videos-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-youtube-trending-videos-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": { "regions": { "title": "Countries", "minItems": 1, "maxItems": 10, "type": "array", "description": "Use this when you need the same official trending chart for one or more countries. Enter ISO 3166-1 alpha-2 codes such as 'US', 'GB', or 'PK'; for example, [\"US\", \"GB\"]. Defaults to [\"US\"] and accepts at most 10 countries per run. This is a country selector, not a language or city filter.", "items": { "type": "string" }, "default": [ "US" ] }, "chart": { "title": "Trending chart", "enum": [ "trendingMusic", "trendingMovieTrailers" ], "type": "string", "description": "Use this when you need a specific official YouTube Trending Chart. Choose 'trendingMusic' for Trending Music Videos or 'trendingMovieTrailers' for Trending Movie Trailers. Defaults to 'trendingMusic', which is the broader of the two public trending charts. This is not a generic YouTube search, Home feed, Gaming Explore feed, or personalized recommendation list.", "default": "trendingMusic" }, "maxResultsPerRegion": { "title": "Maximum videos per country", "minimum": 1, "maximum": 30, "type": "integer", "description": "Use this when you need to cap the number of ranked videos kept from each country chart. Enter an integer from 1 to 30; for example, 10 returns the top ten available entries per country. Defaults to 30, the current public chart maximum. This is a per-country result cap, not a page count or a global total.", "default": 30 }, "language": { "title": "Chart interface language", "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$", "type": "string", "description": "Use this when you want YouTube's chart labels requested in a particular language. Enter a BCP 47 language tag such as 'en', 'es', or 'pt-BR'. Defaults to 'en'; titles and creator names remain exactly as supplied by YouTube. This changes chart interface localization only, not the chart's country ranking.", "default": "en" } } }, "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 } } } } } } } } } } ```