# YouTube Videos Trending API (https://www.socialcrawl.dev/platforms/youtube/videos-trending)

> Returns the most popular (trending) YouTube videos for a region and category (title, thumbnail, duration, view/like/comment counts, channel, and publish time) plus a `cursor` when more results are available. Filter by `region` (ISO country) and `category` (YouTube category id); forward `cursor` for subsequent pages. Send `include=channel` to add each video's channel subscriber count (`post.ext.author_followers`) in the same call.

TL;DR: `GET /v1/youtube/videos/trending` costs 1 credit for the page. include=channel adds 1 credit per distinct channel filled, at most 5 per 50 channels; channels that could not be read are refunded, and a repeat of the same call within the cache window costs 0. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `region` | no | ISO 3166-1 alpha-2 country code (e.g. US, GB, KR). |
| `category` | no | YouTube video category id (e.g. 10 = Music, 20 = Gaming), or a name: music, gaming, sports, news. The chart weights the category rather than filtering strictly, so check `post.ext.categoryTitle` on each row. Any other word is a free 400. |
| `language` | no | Localization language (ISO 639-1) for titles/metadata. |
| `max_results` | no | Maximum number of videos to return (1-50). |
| `cursor` | no | Pagination cursor from a previous response: fetches the next page. |
| `include` | no | Set to `channel` (one token only) to add each row's channel stats in this one call. `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time. (channel) |
| `since` | no | Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. |
| `until` | no | Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. |
| `max_pages` | no | 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. |
| `max_items` | no | 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. |
| `max_credits` | no | 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/youtube/videos/trending" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I get trending YouTube videos via API?

Send a GET to /v1/youtube/videos/trending with a region and optional category. The response lists the most popular videos with title, thumbnail, duration, view, like and comment counts, channel, and publish time. Add include=channel for each channel's subscriber count.

### Can I get trending videos for a specific country?

Yes. Pass region with an ISO country code like US, GB, or KR to get that country's trending list. Add category (for example 10 for Music) to narrow it further.

### How do I page through more trending results?

Each response includes a cursor when more results exist. Forward it as cursor=... on the next request to fetch the next page.

### How many trending videos can I request at once?

Use max_results to set a page size from 1 to 50. Combine it with the cursor to walk the full trending feed for a region.

### How much does the trending endpoint cost?

It costs 1 to 6 credits per request: the page price, plus one credit for each channel include=channel filled, and every new account starts with 100 free credits.

See the full YouTube API: https://www.socialcrawl.dev/platforms/youtube

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to get trending YouTube videos by country via API
- YouTube trending videos API without Data API quota