SocialCrawl

YouTube data API

Read channels, videos and comments from YouTube with one key and one response shape.

Read every tab of a YouTube channel, full video detail, threaded comments, two kinds of search, trending, transcripts and subtitle files, media streams, and batch endpoints that take a thousand ids at a time. Every endpoint returns the same response shape, with the channel under author and each video under post.

Choosing between /v1/youtube/video/subtitles (1cr caption files) and /v1/youtube/video/transcript (3cr cleaned transcript)? See Which endpoint should I use?.

Your first call

1. Fetch a profile

cURL
curl "https://www.socialcrawl.dev/v1/youtube/channel?handle=MrBeast" \
  -H "x-api-key: sc_your_key_here"
TypeScript
const url = new URL("https://www.socialcrawl.dev/v1/youtube/channel");
url.searchParams.set("handle", "MrBeast");
const res = await fetch(url, {
  headers: { "x-api-key": process.env.SOCIALCRAWL_API_KEY! },
});
const { data } = await res.json();
console.log(data.author.display_name, data.author.followers);
Python
import os
import requests

res = requests.get(
    "https://www.socialcrawl.dev/v1/youtube/channel",
    headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]},
    params={"handle": "MrBeast"},
)
author = res.json()["data"]["author"]
print(author["display_name"], author["followers"])

The response is one author object: the channel id, handle, description, subscriber count, video count and, under ext, the country, total views and topic categories. Measured on 22/11/2026: this call took under 1 second and cost 1 credit.

2. Fetch their content

cURL
curl "https://www.socialcrawl.dev/v1/youtube/channel/videos?handle=MrBeast" \
  -H "x-api-key: sc_your_key_here"

3. Read computed fields

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include engagement_rate, language, content_category, and estimated_reach. See Computed fields for formulas, clamping rules, and null semantics. Where an endpoint supports them, list rows also carry judged labels (computed.labels, computed.relevance) by default at no extra credits; see Labels.

What it covers

What you wantCall
Subscriber count, country and descriptionGET /v1/youtube/channel
A channel's business emailGET /v1/youtube/channel/about
Channel, recent videos and metrics in one callGET /v1/youtube/profile/full
Uploads, Shorts or live streamsGET /v1/youtube/channel/videos, GET /v1/youtube/channel/shorts, GET /v1/youtube/channel/lives
Playlists, community posts or podcastsGET /v1/youtube/channel/playlists, GET /v1/youtube/channel/community-posts, GET /v1/youtube/channel/podcasts
Videos inside one channel for a keywordGET /v1/youtube/channel/search
Videos, channels and playlists for a keywordGET /v1/youtube/search, GET /v1/youtube/search/advanced
A hashtag's feed, or autocomplete for a queryGET /v1/youtube/search/hashtag, GET /v1/youtube/search/suggestions
One video in fullGET /v1/youtube/video
Videos YouTube suggests nextGET /v1/youtube/video/related
Comments, or the replies in a threadGET /v1/youtube/video/comments, GET /v1/youtube/video/comment/replies
What is said in a videoGET /v1/youtube/video/transcript, GET /v1/youtube/video/subtitles, POST /v1/youtube/transcripts
Paid promotion and likely sponsorsGET /v1/youtube/video/sponsors
Audio, video files and thumbnailsGET /v1/youtube/video/audio, GET /v1/youtube/video/files, GET /v1/youtube/video/thumbnails
A playlist and its videosGET /v1/youtube/playlist, GET /v1/youtube/playlist/items
One community postGET /v1/youtube/community-post
What is trendingGET /v1/youtube/videos/trending, GET /v1/youtube/shorts/trending
Many videos or channels by idPOST /v1/youtube/videos, POST /v1/youtube/channels

The full list, with credits per call, is under All endpoints.

What it does not cover

  • Analytics only the owner sees. Watch time, revenue and audience data are not returned.
  • Exact subscriber counts. YouTube rounds the figure to three significant figures above 1,000 subscribers, and a channel can hide its count entirely.
  • Auto-dubbed transcripts. video/transcript returns the video's own audio language.
  • Long-lived media links. The URLs from video/audio and video/files expire, so store the video id and ask again when you need the bytes.
  • A handle or avatar on a plain Shorts search row. Add include=engagement,channel to fill them.

A channel has five tabs, and each has its own endpoint

The channel/videos call returns regular uploads only. Everything else lives behind its own call.

What you wantEndpoint
The account snapshotGET /v1/youtube/channel
Regular uploadsGET /v1/youtube/channel/videos
ShortsGET /v1/youtube/channel/shorts
Live and past streamsGET /v1/youtube/channel/lives
PlaylistsGET /v1/youtube/channel/playlists
Text and image postsGET /v1/youtube/channel/community-posts

All five channel-scoped endpoints take either channelId or handle (one is required), and all cost 1 credit on a plain call. The channel call also accepts a url. They page with continuationToken. On the videos, Shorts and live lists, include=channel adds each row's subscriber count for 1 more credit.

Add includeExtras=true to channel/videos to fill likes, comments and description on each row. The sort=oldest option lists a channel from its first upload, with exact dates but null counts. Pass those ids to POST /v1/youtube/videos for exact counts. The channel/search call searches one channel's videos for a keyword.

cURL
# Shorts, not uploads
curl "https://www.socialcrawl.dev/v1/youtube/channel/shorts?handle=MrBeast" \
  -H "x-api-key: sc_your_key_here"

# Uploads with engagement counts attached
curl "https://www.socialcrawl.dev/v1/youtube/channel/videos?handle=MrBeast&includeExtras=true&sort=popular" \
  -H "x-api-key: sc_your_key_here"

The profile/full call combines the channel, its recent videos and computed metrics. If the videos fail, the profile still returns, with a legs[] field that explains why.

Two searches, and they return different things

GET /v1/youtube/searchGET /v1/youtube/search/advanced
ReturnsVideos, channels, playlists, Shorts and live streamsVideos only
FiltersuploadDate, sortBy, type, duration, region, featurespublished_after, published_before, license, category, event_type, video_caption, video_definition, video_dimension, video_embeddable, topic_id, location with location_radius, safe_search

Use search when you need channels or playlists back, and search/advanced when a keyword search is too blunt. The features filter keeps only videos YouTube marks as live, 4K, HD, subtitled and so on, and every feature must match. A search cursor expires after an hour. The includeExtras=true option on search/advanced adds a flat 5 credits for view, like and comment counts. The include option adds at most 5 credits per value, as the section on subscriber counts explains.

The search/hashtag call reads a hashtag feed, with type=shorts to restrict it. The search/suggestions call returns YouTube's autocomplete list, the cheapest keyword-research call here.

sortBy=popular on search is not a view-count sort. Results do not come back in descending view order, and the page caps at roughly 20 results. It cannot be combined with type=shorts (rejected with a 400). For a view-faithful order use search/advanced with order=viewCount&includeExtras=true, then sort on engagement.views. The duration filter on search is currently not applied, so filter client-side on post.content.duration_seconds.

cURL
# Videos from a date window, with counts hydrated
curl "https://www.socialcrawl.dev/v1/youtube/search/advanced?query=ai%20agents&published_after=2026-06-01&order=viewCount&includeExtras=true" \
  -H "x-api-key: sc_your_key_here"

# What does YouTube think people are searching for?
curl "https://www.socialcrawl.dev/v1/youtube/search/suggestions?query=how%20to%20train" \
  -H "x-api-key: sc_your_key_here"

One video, and everything hanging off it

  • The video call returns the complete record from a video url. List rows are lighter, so use it when you need the description or tags. Add include=availability to read where and how it plays in post.ext.playback_availability, including available_countries. It adds 1 credit, refunded with availability_unavailable in data._warnings when the lookup fails.
  • The video/comment/replies call opens one thread. Pass the comment's comment.id (or its comment.ext.replies_token) as continuationToken, then page with next_cursor until has_more is false.
  • The video/transcript call returns timestamped segments in the video's own audio language, never an auto-dubbed translation. A video without captions returns a 404 naming the reason, which is the expected result.
  • The video/subtitles call returns the caption track files, auto-generated included. Cheaper than transcript when you want files rather than text.
  • The video/sponsors call infers paid promotion, so every row carries a confidence score.
cURL
# The whole comment tree on one video
curl "https://www.socialcrawl.dev/v1/youtube/video/comments?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ&order=top" \
  -H "x-api-key: sc_your_key_here"

# Then open one thread with the token that came back
curl "https://www.socialcrawl.dev/v1/youtube/video/comment/replies?continuationToken=TOKEN_FROM_PREVIOUS_RESPONSE" \
  -H "x-api-key: sc_your_key_here"

Comments from a date window

Comments turned off. When an owner turns comments off, video/comments returns a free 200 with no rows and data.comments_disabled: true, rather than a 404. On video, post.ext.comments_disabled is true.

Send since (and optionally until) to video/comments for a date window. The since option sets order=newest, drops older rows, and ends the walk at the first page that reaches one, so you pay only for the pages walked. A pinned comment can defy the sort, so filter rows on comment.published_at rather than stopping at the first old row.

cURL
curl "https://www.socialcrawl.dev/v1/youtube/video/comments?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ&order=newest" \
  -H "x-api-key: sc_your_key_here"

Playlists and community posts

The playlist and playlist/items calls both take a playlist_id and return the same rows in playlist order, without view, like or comment counts or durations. Add include=engagement to fill them in the same call. The playlist call has a second source behind it, so prefer it when uptime matters.

The community-post call takes a single post url. The channel/community-posts call lists a whole channel's posts.

The videos/trending call takes region, category, language and max_results. The category option takes YouTube's numeric id (10 is Music) or music, gaming, sports or news. Check post.ext.categoryTitle, because the chart weights a category without filtering strictly. The shorts/trending call takes only include and returns one global list. Both accept include=channel.

Batch: one call, up to a thousand ids

Three POST endpoints take a JSON body when you already hold ids:

  • POST /v1/youtube/videos takes up to 1000 video ids. Ids that do not resolve are absent from the list.
  • POST /v1/youtube/channels takes up to 1000 bare UC channel ids and returns the same object as channel, subscriber count included. Join on author.id, never on array position, because the response can be shorter than the request. Handles and URLs are rejected with a 400 before billing.
  • POST /v1/youtube/transcripts takes up to 100 video ids. A video without captions comes back not-found, and failed ids are refunded.

The videos and channels calls bill per chunk of 50 ids, so there is no per-id refund on these two.

cURL
curl -X POST "https://www.socialcrawl.dev/v1/youtube/transcripts" \
  -H "x-api-key: sc_your_key_here" \
  -H "content-type: application/json" \
  -d '{"ids":["dQw4w9WgXcQ","9bZkp7q19f0"],"language":"en"}'

Subscriber counts next to search results

Add include=channel and every result carries its channel's subscriber count on post.ext.author_followers, and the country on post.ext.author_country when the channel lists one. Add include=engagement too for Shorts, which arrive without a channel.

cURL
curl "https://www.socialcrawl.dev/v1/youtube/search?query=iphone17&type=shorts&include=engagement,channel" \
  -H "x-api-key: sc_your_key_here"

The include=engagement option fills likes, comments, duration and post.ext.channel_id from a per-video lookup. Each join costs 1 credit per distinct video or channel it filled, never more than 5 per 50, and anything it could not fill is refunded. Both values work on search/hashtag, playlist, playlist/items and channel/lives. The include=channel option alone works on search/advanced, videos/trending, shorts/trending, channel/videos and channel/shorts.

For a crawl that meets the same channels on many pages, collect the channel ids, deduplicate them and resolve them once with POST /v1/youtube/channels.

cURL
curl -X POST "https://www.socialcrawl.dev/v1/youtube/channels" \
  -H "x-api-key: sc_your_key_here" \
  -H "content-type: application/json" \
  -d '{"ids":["UCn9l4gU5mkmmlC2eiVu0LHw","UC_x5XG1OV2P6uZZ5FSM9Ttw"]}'

YouTube rounds author.followers to three significant figures above 1,000 subscribers, so you will see 12,800,000 and never the exact digits. Those channels also set author.ext.followers_approximate to true. A channel that hides its count sets author.ext.hiddenSubscriberCount to true, which is the signal to drop it from a ratio rather than treat a zero as real.

Labels

These lists label their rows by default, at no extra credit. Comments carry sentiment, question, purchase_intent and complaint on computed.labels. Rows on /v1/youtube/search carry sponsored, intent, niche and computed.relevance. Send judgments=off to skip them. See Labels for the field shapes.

Questions people ask

The GET /v1/youtube/video/related call takes the video url and returns the "up next" list YouTube shows beside the video, in YouTube's order. The list changes between calls and has no cursor. Views are YouTube's rounded figure until you add include=engagement.

cURL
curl "https://www.socialcrawl.dev/v1/youtube/video/related?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: sc_your_key_here"

How do I get a channel's business email and country?

The GET /v1/youtube/channel/about call takes handle, channelId or url and returns author.ext.public_email and author.ext.country. It costs 25 credits, charged only when an address comes back. Try GET /v1/youtube/channel first at 1 credit, because it already returns author.ext.public_email when the channel writes an address in its public description. A first read of a hidden address can take up to 5 minutes, so set your HTTP timeout to at least 300 seconds. If it is not ready, the call answers 503 with a Retry-After header, uncharged. See Creator email.

Can I get subscriber counts on YouTube search results?

Yes. Add include=channel to GET /v1/youtube/search, and see Subscriber counts next to search results.

What is the difference between community-post and channel/community-posts?

The GET /v1/youtube/community-post call takes the url of one post and returns that post. The GET /v1/youtube/channel/community-posts call takes a handle or channelId and lists a whole channel's posts, paged with continuationToken. Use the single call when you already hold a post link.

Are YouTube counts exact?

Subscriber counts are not: YouTube rounds author.followers to three significant figures above 1,000. View counts on list rows can also be rounded or null. For exact counts, add include=engagement to the list call, or pass the video ids to POST /v1/youtube/videos.

All endpoints

32 endpoints available.

EndpointPathCredit Tier
Get YouTube channel info/v1/youtube/channelstandard (1cr)
List a YouTube channel's community posts/v1/youtube/channel/community-postsstandard (1-2cr)metered
List a YouTube channel's live streams/v1/youtube/channel/livesstandard (1-7cr)metered
List a YouTube channel's playlists/v1/youtube/channel/playlistsstandard (1cr)
List a YouTube channel's podcasts/v1/youtube/channel/podcastsstandard (1cr)
Search inside one YouTube channel/v1/youtube/channel/searchstandard (1-7cr)metered
List YouTube channel shorts/v1/youtube/channel/shortsstandard (1-2cr)metered
List YouTube channel videos/v1/youtube/channel/videosstandard (1-2cr)metered
Get YouTube community post/v1/youtube/community-poststandard (1cr)
Get YouTube playlist/v1/youtube/playliststandard (1-11cr)metered
List the videos in a YouTube playlist/v1/youtube/playlist/itemsstandard (1-11cr)metered
YouTube profile, recent posts, and computed analytics in one call./v1/youtube/profile/fullstandard (5cr)
Search YouTube/v1/youtube/searchstandard (1-19cr)metered
Advanced YouTube video search/v1/youtube/search/advancedstandard (1-11cr)metered
Search YouTube by hashtag/v1/youtube/search/hashtagstandard (1-11cr)metered
Get YouTube search suggestions/v1/youtube/search/suggestionsstandard (1cr)
Up to 100 YouTube video ids → one transcript per row, failed ids refunded./v1/youtube/transcriptsstandard (3-300cr)metered
Get YouTube video details/v1/youtube/videostandard (1-2cr)metered
List YouTube comment replies/v1/youtube/video/comment/repliesstandard (1-5cr)metered
List YouTube video comments/v1/youtube/video/commentsstandard (1-5cr)metered
Get videos related to a YouTube video/v1/youtube/video/relatedstandard (1-11cr)metered
Get a YouTube video's subtitle files/v1/youtube/video/subtitlesstandard (1cr)
Get a YouTube video's thumbnail files/v1/youtube/video/thumbnailsstandard (1cr)
Get YouTube video transcript/v1/youtube/video/transcriptstandard (3cr)
Get trending YouTube videos/v1/youtube/videos/trendingstandard (1-6cr)metered
Batch get YouTube channel details (up to 1000)/v1/youtube/channelsadvanced (5-100cr)metered
Get trending YouTube shorts/v1/youtube/shorts/trendingadvanced (5-15cr)metered
Get a YouTube video's audio file streams/v1/youtube/video/audioadvanced (5cr)
Get a YouTube video's video file streams/v1/youtube/video/filesadvanced (5cr)
Batch get YouTube video details (up to 1000)/v1/youtube/videosadvanced (5-100cr)metered
Get a YouTube channel's contact email and country. Try the 1-credit youtube/channel first: it already carries the email for some channels, and you are charged here only when an address is returned. A first read of an address behind the View email address button can take up to 5 minutes, so set your HTTP timeout to at least 300s; on a 503, retry after the Retry-After seconds/v1/youtube/channel/aboutpremium (25cr)
Detect sponsors of a YouTube video/v1/youtube/video/sponsorspremium (10cr)

How far back and how deep

Each list returns one page at a time. Send cursor for the next page, or max_items or max_pages to collect several pages in one call. A page size appears only where it has been verified. How paging works

PathRows per pageDate windowOne call collects
/v1/youtube/channel/community-postsabout 10since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/channel/livesabout 30since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/channel/playlistsvariessince and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/channel/podcastsvariessince and until, applied to each page fetchedone page a call
/v1/youtube/channel/searchabout 29since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/channel/shortsvariessince and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/channel/videosabout 30since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/playlistvariessince and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/playlist/itemsabout 50since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/profile/fullvariesnoneone page a call
/v1/youtube/searchabout 20since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/search/advancedvariessince and until. Newest first with order=date, so a walk stops at since.up to 5,000 rows or 50 pages
/v1/youtube/search/hashtagabout 26since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/shorts/trendingvariessince and until, applied to each page fetchedone page a call
/v1/youtube/video/comment/repliesabout 100since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/youtube/video/commentsvariessince and until. Newest first with order=newest, so a walk stops at since.up to 5,000 rows or 50 pages
/v1/youtube/video/relatedvariessince and until, applied to each page fetchedone page a call
/v1/youtube/videos/trendingvariessince and until, applied to each page fetchedup to 5,000 rows or 50 pages

Country and region

country and region do different jobs on different endpoints. Each line below says what the parameter does there. How they differ

  • region on /v1/youtube/search: 2-letter country code of the country to put the proxy in.
  • region on /v1/youtube/search/advanced: ISO 3166-1 alpha-2 country code.
  • region on /v1/youtube/search/suggestions: ISO 3166-1 alpha-2 country code to localize suggestions.
  • region on /v1/youtube/videos/trending: ISO 3166-1 alpha-2 country code (e.g. US, GB, KR).

How long a call takes

Measured on production calls that were not served from the cache, 14/10/2026 to 21/10/2026. A cached call answers faster. Set your client timeout to the value in Timeout to set, so a slow call is not cut off and sent again.

PathTypical (median)95% finish withinTimeout to set
/v1/youtube/channel0.2 s1.0 s10 s
/v1/youtube/channel/about2.2 s49 s120 s
/v1/youtube/channel/community-posts0.9 s1.9 s10 s
/v1/youtube/channel/lives1.4 s2.9 s10 s
/v1/youtube/channel/shorts6.6 s15 s60 s
/v1/youtube/channel/videos5.7 s9.4 s33 s
/v1/youtube/channels0.3 s1.0 s10 s
/v1/youtube/community-post1.5 s3.9 s10 s
/v1/youtube/playlist/items0.7 s1.5 s10 s
/v1/youtube/profile/full6.8 s11 s24 s
/v1/youtube/search2.5 s6.6 s15 s
/v1/youtube/search/advanced0.7 s1.4 s10 s
/v1/youtube/search/hashtag1.9 s4.0 s10 s
/v1/youtube/search/suggestions0.2 s0.9 s10 s
/v1/youtube/shorts/trending10 s18 s37 s
/v1/youtube/transcripts1.4 s23 s56 s
/v1/youtube/video0.1 s0.8 s10 s
/v1/youtube/video/audio0.9 s2.3 s10 s
/v1/youtube/video/comment/replies0.5 s1.1 s10 s
/v1/youtube/video/comments1.0 s4.2 s10 s
/v1/youtube/video/files0.9 s2.3 s10 s
/v1/youtube/video/related2.4 s5.6 s12 s
/v1/youtube/video/subtitles1.0 s1.8 s10 s
/v1/youtube/video/transcript1.1 s5.2 s18 s
/v1/youtube/videos0.4 s1.0 s10 s
/v1/youtube/videos/trending0.3 s1.1 s10 s

Platform notes

  • Everything is GET with query parameters except the three batch endpoints, which take a POST JSON body.
  • Channel calls take channelId or handle, video calls take the video url, and playlist calls take playlist_id.
  • Pagination is continuationToken on the channel, search, comments and hashtag endpoints, and cursor on playlist, playlist/items, videos/trending and search/advanced. Pass back whatever the previous response returned.
  • The hl option on channel, video and the id-batch endpoints sets the language of the returned metadata.

Next steps

Official YouTube Resources