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 "https://www.socialcrawl.dev/v1/youtube/channel?handle=MrBeast" \
-H "x-api-key: sc_your_key_here"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);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 "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 want | Call |
|---|---|
| Subscriber count, country and description | GET /v1/youtube/channel |
| A channel's business email | GET /v1/youtube/channel/about |
| Channel, recent videos and metrics in one call | GET /v1/youtube/profile/full |
| Uploads, Shorts or live streams | GET /v1/youtube/channel/videos, GET /v1/youtube/channel/shorts, GET /v1/youtube/channel/lives |
| Playlists, community posts or podcasts | GET /v1/youtube/channel/playlists, GET /v1/youtube/channel/community-posts, GET /v1/youtube/channel/podcasts |
| Videos inside one channel for a keyword | GET /v1/youtube/channel/search |
| Videos, channels and playlists for a keyword | GET /v1/youtube/search, GET /v1/youtube/search/advanced |
| A hashtag's feed, or autocomplete for a query | GET /v1/youtube/search/hashtag, GET /v1/youtube/search/suggestions |
| One video in full | GET /v1/youtube/video |
| Videos YouTube suggests next | GET /v1/youtube/video/related |
| Comments, or the replies in a thread | GET /v1/youtube/video/comments, GET /v1/youtube/video/comment/replies |
| What is said in a video | GET /v1/youtube/video/transcript, GET /v1/youtube/video/subtitles, POST /v1/youtube/transcripts |
| Paid promotion and likely sponsors | GET /v1/youtube/video/sponsors |
| Audio, video files and thumbnails | GET /v1/youtube/video/audio, GET /v1/youtube/video/files, GET /v1/youtube/video/thumbnails |
| A playlist and its videos | GET /v1/youtube/playlist, GET /v1/youtube/playlist/items |
| One community post | GET /v1/youtube/community-post |
| What is trending | GET /v1/youtube/videos/trending, GET /v1/youtube/shorts/trending |
| Many videos or channels by id | POST /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/transcriptreturns the video's own audio language. - Long-lived media links. The URLs from
video/audioandvideo/filesexpire, 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,channelto 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 want | Endpoint |
|---|---|
| The account snapshot | GET /v1/youtube/channel |
| Regular uploads | GET /v1/youtube/channel/videos |
| Shorts | GET /v1/youtube/channel/shorts |
| Live and past streams | GET /v1/youtube/channel/lives |
| Playlists | GET /v1/youtube/channel/playlists |
| Text and image posts | GET /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.
# 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/search | GET /v1/youtube/search/advanced | |
|---|---|---|
| Returns | Videos, channels, playlists, Shorts and live streams | Videos only |
| Filters | uploadDate, sortBy, type, duration, region, features | published_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.
# 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
videocall returns the complete record from a videourl. List rows are lighter, so use it when you need the description or tags. Addinclude=availabilityto read where and how it plays inpost.ext.playback_availability, includingavailable_countries. It adds 1 credit, refunded withavailability_unavailableindata._warningswhen the lookup fails. - The
video/comment/repliescall opens one thread. Pass the comment'scomment.id(or itscomment.ext.replies_token) ascontinuationToken, then page withnext_cursoruntilhas_moreisfalse. - The
video/transcriptcall returns timestamped segments in the video's own audio language, never an auto-dubbed translation. A video without captions returns a404naming the reason, which is the expected result. - The
video/subtitlescall returns the caption track files, auto-generated included. Cheaper thantranscriptwhen you want files rather than text. - The
video/sponsorscall infers paid promotion, so every row carries a confidence score.
# 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 "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.
Trending
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/videostakes up to 1000 video ids. Ids that do not resolve are absent from the list.POST /v1/youtube/channelstakes up to 1000 bareUCchannel ids and returns the same object aschannel, subscriber count included. Join onauthor.id, never on array position, because the response can be shorter than the request. Handles and URLs are rejected with a400before billing.POST /v1/youtube/transcriptstakes 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 -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 "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 -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
How do I get the videos related to a video?
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 "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.
| Endpoint | Path | Credit Tier |
|---|---|---|
| Get YouTube channel info | /v1/youtube/channel | standard (1cr) |
| List a YouTube channel's community posts | /v1/youtube/channel/community-posts | standard (1-2cr)metered |
| List a YouTube channel's live streams | /v1/youtube/channel/lives | standard (1-7cr)metered |
| List a YouTube channel's playlists | /v1/youtube/channel/playlists | standard (1cr) |
| List a YouTube channel's podcasts | /v1/youtube/channel/podcasts | standard (1cr) |
| Search inside one YouTube channel | /v1/youtube/channel/search | standard (1-7cr)metered |
| List YouTube channel shorts | /v1/youtube/channel/shorts | standard (1-2cr)metered |
| List YouTube channel videos | /v1/youtube/channel/videos | standard (1-2cr)metered |
| Get YouTube community post | /v1/youtube/community-post | standard (1cr) |
| Get YouTube playlist | /v1/youtube/playlist | standard (1-11cr)metered |
| List the videos in a YouTube playlist | /v1/youtube/playlist/items | standard (1-11cr)metered |
| YouTube profile, recent posts, and computed analytics in one call. | /v1/youtube/profile/full | standard (5cr) |
| Search YouTube | /v1/youtube/search | standard (1-19cr)metered |
| Advanced YouTube video search | /v1/youtube/search/advanced | standard (1-11cr)metered |
| Search YouTube by hashtag | /v1/youtube/search/hashtag | standard (1-11cr)metered |
| Get YouTube search suggestions | /v1/youtube/search/suggestions | standard (1cr) |
| Up to 100 YouTube video ids → one transcript per row, failed ids refunded. | /v1/youtube/transcripts | standard (3-300cr)metered |
| Get YouTube video details | /v1/youtube/video | standard (1-2cr)metered |
| List YouTube comment replies | /v1/youtube/video/comment/replies | standard (1-5cr)metered |
| List YouTube video comments | /v1/youtube/video/comments | standard (1-5cr)metered |
| Get videos related to a YouTube video | /v1/youtube/video/related | standard (1-11cr)metered |
| Get a YouTube video's subtitle files | /v1/youtube/video/subtitles | standard (1cr) |
| Get a YouTube video's thumbnail files | /v1/youtube/video/thumbnails | standard (1cr) |
| Get YouTube video transcript | /v1/youtube/video/transcript | standard (3cr) |
| Get trending YouTube videos | /v1/youtube/videos/trending | standard (1-6cr)metered |
| Batch get YouTube channel details (up to 1000) | /v1/youtube/channels | advanced (5-100cr)metered |
| Get trending YouTube shorts | /v1/youtube/shorts/trending | advanced (5-15cr)metered |
| Get a YouTube video's audio file streams | /v1/youtube/video/audio | advanced (5cr) |
| Get a YouTube video's video file streams | /v1/youtube/video/files | advanced (5cr) |
| Batch get YouTube video details (up to 1000) | /v1/youtube/videos | advanced (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/about | premium (25cr) |
| Detect sponsors of a YouTube video | /v1/youtube/video/sponsors | premium (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
| Path | Rows per page | Date window | One call collects |
|---|---|---|---|
/v1/youtube/channel/community-posts | about 10 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/channel/lives | about 30 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/channel/playlists | varies | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/channel/podcasts | varies | since and until, applied to each page fetched | one page a call |
/v1/youtube/channel/search | about 29 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/channel/shorts | varies | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/channel/videos | about 30 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/playlist | varies | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/playlist/items | about 50 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/profile/full | varies | none | one page a call |
/v1/youtube/search | about 20 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/search/advanced | varies | since and until. Newest first with order=date, so a walk stops at since. | up to 5,000 rows or 50 pages |
/v1/youtube/search/hashtag | about 26 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/shorts/trending | varies | since and until, applied to each page fetched | one page a call |
/v1/youtube/video/comment/replies | about 100 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/youtube/video/comments | varies | since and until. Newest first with order=newest, so a walk stops at since. | up to 5,000 rows or 50 pages |
/v1/youtube/video/related | varies | since and until, applied to each page fetched | one page a call |
/v1/youtube/videos/trending | varies | since and until, applied to each page fetched | up 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
regionon/v1/youtube/search: 2-letter country code of the country to put the proxy in.regionon/v1/youtube/search/advanced: ISO 3166-1 alpha-2 country code.regionon/v1/youtube/search/suggestions: ISO 3166-1 alpha-2 country code to localize suggestions.regionon/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.
| Path | Typical (median) | 95% finish within | Timeout to set |
|---|---|---|---|
/v1/youtube/channel | 0.2 s | 1.0 s | 10 s |
/v1/youtube/channel/about | 2.2 s | 49 s | 120 s |
/v1/youtube/channel/community-posts | 0.9 s | 1.9 s | 10 s |
/v1/youtube/channel/lives | 1.4 s | 2.9 s | 10 s |
/v1/youtube/channel/shorts | 6.6 s | 15 s | 60 s |
/v1/youtube/channel/videos | 5.7 s | 9.4 s | 33 s |
/v1/youtube/channels | 0.3 s | 1.0 s | 10 s |
/v1/youtube/community-post | 1.5 s | 3.9 s | 10 s |
/v1/youtube/playlist/items | 0.7 s | 1.5 s | 10 s |
/v1/youtube/profile/full | 6.8 s | 11 s | 24 s |
/v1/youtube/search | 2.5 s | 6.6 s | 15 s |
/v1/youtube/search/advanced | 0.7 s | 1.4 s | 10 s |
/v1/youtube/search/hashtag | 1.9 s | 4.0 s | 10 s |
/v1/youtube/search/suggestions | 0.2 s | 0.9 s | 10 s |
/v1/youtube/shorts/trending | 10 s | 18 s | 37 s |
/v1/youtube/transcripts | 1.4 s | 23 s | 56 s |
/v1/youtube/video | 0.1 s | 0.8 s | 10 s |
/v1/youtube/video/audio | 0.9 s | 2.3 s | 10 s |
/v1/youtube/video/comment/replies | 0.5 s | 1.1 s | 10 s |
/v1/youtube/video/comments | 1.0 s | 4.2 s | 10 s |
/v1/youtube/video/files | 0.9 s | 2.3 s | 10 s |
/v1/youtube/video/related | 2.4 s | 5.6 s | 12 s |
/v1/youtube/video/subtitles | 1.0 s | 1.8 s | 10 s |
/v1/youtube/video/transcript | 1.1 s | 5.2 s | 18 s |
/v1/youtube/videos | 0.4 s | 1.0 s | 10 s |
/v1/youtube/videos/trending | 0.3 s | 1.1 s | 10 s |
Platform notes
- Everything is
GETwith query parameters except the three batch endpoints, which take aPOSTJSON body. - Channel calls take
channelIdorhandle, video calls take the videourl, and playlist calls takeplaylist_id. - Pagination is
continuationTokenon the channel, search, comments and hashtag endpoints, andcursoronplaylist,playlist/items,videos/trendingandsearch/advanced. Pass back whatever the previous response returned. - The
hloption onchannel,videoand the id-batch endpoints sets the language of the returned metadata.
Next steps
Pagination
Cursor and continuation-token walks, and what has_more actually means.
Credits
What each tier costs and when a call is refunded.
Creator email
Find the business address behind a channel's View email address button.
Official YouTube Resources
- YouTube Data API v3: Official Google developer documentation
- YouTube Analytics API: Channel and video analytics
