# YouTube Video Related API (https://www.socialcrawl.dev/platforms/youtube/video-related)

> Returns the videos YouTube lists next to a video (its "up next" list), usually 11 or 12, in the order YouTube shows them. Each row carries the video id, URL, title, thumbnail, duration, view count and channel name, and the channel id when YouTube gives one. The list is what YouTube shows a signed-out viewer at the moment of the call, so it changes between calls. VIEWS are YouTube's rounded figure ("2.5B" is 2,500,000,000); send `include=engagement` for exact counts. With `language`, YouTube writes the labels in that language ("416 mil") and they are read at the same rounding. DATES: the list only labels each video ("16y ago"), so by default every row is joined to the per-video lookup for its exact publish second and its channel, at no extra credit (one lookup per page); with `exact_dates=false` no lookup runs and `post.published_at` is null. `post.author.username` is the channel's @handle, or null for a channel that has none (`include=channel` fills it where it exists). Send `include=engagement` for likes and comments, and `include=channel` for the channel's subscriber count and avatar. TITLES: the free lookup swaps a machine-translated listing title for the creator's own; a title not swapped carries `post.ext.title_maybe_translated: true`. Accepts a watch, youtu.be or Shorts URL. A video that does not exist is a 404 and is not charged.

TL;DR: `GET /v1/youtube/video/related` costs 1 credit for the page. include=engagement and include=channel each add 1 credit per distinct video or channel filled, at most 5 per join on a page of up to 50 rows, so a page with both is at most 11 credits; ids that could not be filled are refunded, and a repeat of the same call within the cache window costs 0. and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Full URL of the YouTube video or Short |
| `language` | no | Preferred language for the listing (mapped to Accept-Language; not guaranteed due to YouTube localization behavior). 2 letter language code, ie 'en', 'es', 'fr' etc. |
| `include` | no | Set to `engagement`, `channel`, or both (`engagement,channel`) to fill more of every row in this one call. `engagement` fills `post.engagement.views`, `.likes` and `.comments`, `post.content.duration_seconds`, `post.ext.channel_id` and `post.author.display_name` where the row lacks them, and replaces a date derived from a label such as "4 months ago" with the exact publish time (removing `post.ext.published_precision`). `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). Send both to cover rows that arrive without a channel id: the video join supplies it and the channel join then uses it. 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. |
| `exact_dates` | no | Exact publish dates are on by default and free. A row whose date the upstream derived from a relative label such as "4 months ago" (measured up to four months off) is joined to the per-video lookup for its exact publish second, at no extra credit: one lookup per page (two on a page past 50 rows, side by side), adding about 0.2 to 0.7 seconds (never more than 3). The same lookup swaps the listing title, often YouTube's English machine translation, for the creator's own, and `computed.language` follows it; a title not swapped carries `post.ext.title_maybe_translated: true`. Set to `false` to skip the lookup: rows then carry the supplier's date estimate (a day-granular or coarser label truncated to midnight UTC), marked by `post.ext.published_precision` and `post.ext.published_label`, and the listing title, marked by `post.ext.title_maybe_translated`. A row the lookup could not resolve keeps those values and markers, and `_warnings` carries `exact_dates_partial` (some rows) or `exact_dates_unavailable` (none); on `channel/videos`, whose dates are already exact, the warnings are `original_titles_partial` and `original_titles_unavailable`. (true \| false) |
| `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`. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/youtube/video/related" \
  --data-urlencode "url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

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