# YouTube Trending Scraper (`receptional_blender/youtube-trending-feed`) Actor

Grab what's blowing up on YouTube right now — one clean row per trending video for any country and category (id, title, channel, view count, published time, duration, thumbnails). Talks straight to YouTube's own InnerTube API, so there's no Data API key and no headless browser.

- **URL**: https://apify.com/receptional\_blender/youtube-trending-feed.md
- **Developed by:** [Assia Fadli](https://apify.com/receptional_blender) (community)
- **Categories:** Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 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.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Scraper

See exactly what's taking off on YouTube **right now**. Pick a category and a country and this
actor hands you one tidy row per trending video — no YouTube Data API key, no headless browser, no
login required.

Under the hood it speaks directly to YouTube's own internal **InnerTube** API (the very endpoints
the YouTube app and website call), which keeps every run fast, cheap and dependable.

### What you get

One dataset row per trending video:

| Field | Description |
| --- | --- |
| `category` | Trending category (`now`, `music`, `gaming`, `movies`) |
| `source` | Which source produced the row — see [How it works](#how-it-works) |
| `rank` | 1-based position in the trending list |
| `videoId` | 11-character video ID |
| `title` | Video title |
| `url` | `https://www.youtube.com/watch?v=<videoId>` |
| `channelName` | Channel display name |
| `channelId` | The channel's `UC…` ID (when available) |
| `channelUrl` | `https://www.youtube.com/channel/<channelId>` (when available) |
| `viewsText` | View count as YouTube's own display text, e.g. `"15,780,087 views"` |
| `viewCount` | Best-effort integer parse of `viewsText`, e.g. `15780087` |
| `publishedText` | Relative publish time, e.g. `"5 days ago"` |
| `lengthText` | Duration, e.g. `"3:25"` |
| `descriptionSnippet` | Short description snippet (when available) |
| `thumbnail` | Highest-resolution thumbnail URL |
| `thumbnails` | Full array of `{ url, width, height }` thumbnails |

If nothing can be fetched for the requested region, the actor still writes a single row —
`{ "category": "…", "region": "…", "error": "…" }` — so a run is never silently empty.

### Input

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `category` | string | no | `now` | `now` (general), `music`, `gaming`, or `movies` |
| `maxResults` | integer | no | `50` | Maximum number of trending videos to return |
| `gl` | string | no | `US` | ISO country code for the trending region (e.g. `US`, `GB`, `DE`, `IN`) |
| `country` | string | no | — | Alias for `gl`; `gl` wins if both are set |
| `language` | string | no | `en` | ISO language code for titles / metadata |
| `proxyCountryCode` | string | no | `US` | ISO country code for the Apify residential proxy exit |

#### Example input

```json
{
    "category": "now",
    "maxResults": 50,
    "gl": "US",
    "proxyCountryCode": "US"
}
```

#### Example output row

```json
{
    "category": "now",
    "source": "most_viewed_this_week",
    "rank": 1,
    "videoId": "qFhspt7zsXg",
    "title": "Number_i - BUGS LIFE (Official Music Video)",
    "url": "https://www.youtube.com/watch?v=qFhspt7zsXg",
    "channelName": "Number_i OFFICIAL",
    "channelId": "UC7N348fUF5Sh-N4m1y578zg",
    "channelUrl": "https://www.youtube.com/channel/UC7N348fUF5Sh-N4m1y578zg",
    "viewsText": "15,780,087 views",
    "viewCount": 15780087,
    "publishedText": "5 days ago",
    "lengthText": "3:25",
    "thumbnail": "https://i.ytimg.com/vi/qFhspt7zsXg/hqdefault.jpg"
}
```

### How it works

YouTube **retired its dedicated Trending feed** (`browseId: "FEtrending"`) in 2025: every InnerTube
client now returns HTTP 400 for it, `/feed/trending` redirects to the (empty, logged-out) home feed,
and the feed no longer appears in the navigation guide. To keep returning a real, up-to-date trending
list, this actor uses a resilient two-step strategy:

1. **Legacy Trending feed (forward-compatibility).** It first POSTs to `youtubei/v1/browse` with
   `browseId: "FEtrending"` (and the classic category `params`) using the **WEB** client. If YouTube
   ever restores this feed, the actor picks it up automatically and rows are tagged
   `source: "trending"`.
2. **Most-viewed-this-week search (the working source today).** When the legacy feed is unavailable,
   it POSTs to `youtubei/v1/search` with the **ANDROID** client, sorting by **view count** and
   restricting to videos **uploaded this week** (search filter `params: "CAMSBAgDEAE="`). A broad
   seed query per category (`now` uses a ubiquitous stop-word so the result reflects the week's
   overall most-viewed videos across every category) surfaces what is currently blowing up. It pages
   through continuation tokens until `maxResults` is reached, de-duplicating by `videoId` and
   guarding against continuation loops. These rows are tagged `source: "most_viewed_this_week"`.

Requests are routed through Apify residential proxy when available, with an automatic fallback to a
direct connection so a blocked or absent proxy never crashes the run.

### Pricing

This actor uses Apify's **pay-per-event** model. You're charged once per trending video delivered to
the dataset (`video-scraped`). Error rows are never billed, and the run stops automatically the
moment your budget is reached.

### Notes & limitations

- Because YouTube removed the official Trending feed, "trending" is currently derived from the
  **most-viewed videos uploaded in the last week** for the chosen category and region. This closely
  tracks what people are watching now, but it is not identical to the old editorially-curated
  Trending page.
- `viewsText`, `publishedText` and `lengthText` are YouTube's own localized display text;
  `viewCount` is a best-effort numeric parse of `viewsText`.
- The region is controlled by `gl` / `country`; for the most accurate regional results, set
  `proxyCountryCode` to the same country.
- YouTube can change its internal API at any time; this actor tolerates several response shapes but
  is not covered by an official API contract.

### Tech

Written in **TypeScript** on the Apify SDK, using `got-scraping` for the InnerTube requests.
HTTP-only, so builds are fast and runs are cheap.

### License

MIT © Assia Fadli

# Actor input Schema

## `category` (type: `string`):

Which trending tab to fetch. "now" returns the week's overall most-viewed videos across all categories; the others are topic-focused.

## `maxResults` (type: `integer`):

Maximum number of trending videos to return. You're charged once per delivered video.

## `gl` (type: `string`):

ISO country code for the trending region, e.g. "US", "GB", "DE", "IN". Controls which country's trending list is returned. Alias: use `country` instead if you prefer.

## `country` (type: `string`):

Alias for the region country code. If both are set, `gl` wins. Leave blank if you already set `gl`.

## `language` (type: `string`):

ISO language code for titles / metadata, e.g. "en", "es", "fr".

## `proxyCountryCode` (type: `string`):

Optional ISO country code for the Apify residential proxy exit (e.g. "US", "GB", "DE"). Best set to the same country as the region. Leave blank to let Apify pick.

## Actor input object example

```json
{
  "category": "now",
  "maxResults": 50,
  "gl": "US",
  "language": "en",
  "proxyCountryCode": "US"
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "category": "now",
    "maxResults": 50,
    "gl": "US",
    "language": "en",
    "proxyCountryCode": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("receptional_blender/youtube-trending-feed").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "category": "now",
    "maxResults": 50,
    "gl": "US",
    "language": "en",
    "proxyCountryCode": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("receptional_blender/youtube-trending-feed").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 '{
  "category": "now",
  "maxResults": 50,
  "gl": "US",
  "language": "en",
  "proxyCountryCode": "US"
}' |
apify call receptional_blender/youtube-trending-feed --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=receptional_blender/youtube-trending-feed",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/eibjVSCamzC4xS5YK/builds/NCj2UojBHZIH3wRgx/openapi.json