YouTube Data API - Search, Videos, Comments, Transcripts, Channels
Search YouTube and retrieve videos, shorts, comments, transcripts, streams, channel data, and community posts with their comments as structured JSON. 17 endpoints across video and channel surfaces.
YouTube via Scavio
Search YouTube and retrieve videos, shorts, search suggestions, video metadata, comments, transcripts, related videos, download streams, full channel data (info, videos, shorts, community posts), and a single community post with its comments. All endpoints return structured JSON.
When to trigger
Use this skill when the user asks to:
- Find YouTube videos, shorts, or channels on a topic
- Get a video's metadata, view count, duration, or captions list
- Read a video's comments and comment replies
- Pull a full transcript or timed subtitles for a video
- Get related videos or direct download stream URLs
- Look up a channel's info, videos, shorts, or community posts
- Resolve a channel handle or URL to a channel ID
- Read one community post by id or URL, or the comments under it
Setup
Get a free API key at scavio.dev (50 free credits to get started, no card required):
export SCAVIO_API_KEY=sk_live_your_key
If you do not have a key yet
An agent running this skill without SCAVIO_API_KEY set will get 401 on every
call below. The whole path from nothing to a working key is self-serve:
- Sign up at dashboard.scavio.dev - email or Google, no card required.
- A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy.
- A new account starts with 50 credits. Endpoints in this skill cost 1 credit each unless the table below says otherwise.
When the balance runs out the API answers 402 with a JSON body carrying
billing_url. Topping up needs no code change - the same key keeps working.
The smallest purchase is 2,500 credits for $25, and monthly plans work out
cheaper per credit if the usage is steady rather than one-off.
Every request is a POST with a JSON body and:
Authorization: Bearer $SCAVIO_API_KEY
Endpoints
Base URL: https://api.scavio.dev. All paths are under /api/v1/youtube.
Video endpoints
| Endpoint | Credits | Description |
|---|---|---|
POST /api/v1/youtube/search | 2 | Search videos (and channels/playlists) |
POST /api/v1/youtube/shorts | 2 | Search Shorts |
POST /api/v1/youtube/suggestions | 1 | Search autocomplete suggestions |
POST /api/v1/youtube/video | 1 | Full video metadata and captions list |
POST /api/v1/youtube/comments | 1 | Top-level comments for a video |
POST /api/v1/youtube/comments/replies | 1 | Replies to a specific comment |
POST /api/v1/youtube/transcript | 5 | Full transcript or timed subtitles |
POST /api/v1/youtube/related | 1 | Videos related to a video |
POST /api/v1/youtube/streams | 3 | Direct playable/downloadable stream URLs |
Channel endpoints
| Endpoint | Credits | Description |
|---|---|---|
POST /api/v1/youtube/channel/search | 1 | Search channels |
POST /api/v1/youtube/channel | 1 | Full channel info |
POST /api/v1/youtube/channel/videos | 1 | A channel's videos |
POST /api/v1/youtube/channel/shorts | 1 | A channel's Shorts |
POST /api/v1/youtube/channel/community | 1 | A channel's community posts |
POST /api/v1/youtube/channel/resolve | 1 | Resolve a handle or URL to a channel ID |
POST /api/v1/youtube/community/post | 1 | One community post by id or URL |
POST /api/v1/youtube/community/post/comments | 1 | Comments on a community post |
POST /api/v1/youtube/metadatastill works as a deprecated alias of/video. Use/videofor new code.
Workflow
- Find a video: call
/searchwithsearch. Usesort_by: view_countfor the most-watched result. Readresults[].video_id. - Get metadata: call
/videowithvideo_id(accepts a full watch URL too) for description,length_seconds,view_count,keywords, andcaptions[]. - Read discussion: call
/comments, then/comments/replieswith a comment'sreply_cursorto expand a thread. - Get the text: call
/transcriptfor a plain transcript (format: text) or timed subtitles (format: srt). - Download: call
/streamsfor direct format URLs. - Channels: resolve a handle with
/channel/resolve, then call/channel,/channel/videos,/channel/shorts, or/channel/community. - Community posts: take a
post_idfrom/channel/community(or a post URL), call/community/postfor the post, then/community/post/commentswith the samepost_id(optionallycursor: comments_cursor) for its comments.
Paginated endpoints return next_cursor and has_more; pass next_cursor back as cursor for the next page.
Parameters
Search (/search)
| Parameter | Type | Default | Description |
|---|---|---|---|
search | string | required | Search query — note: this field is search, not query |
upload_date | string | -- | last_hour, today, this_week, this_month, this_year |
type | string | -- | video, channel, playlist, or movie |
duration | string | -- | short, medium, long |
sort_by | string | relevance | relevance, date, view_count, rating |
features | string[] | -- | Any of hd, 4k, subtitles, creative_commons, live, 360, 3d, hdr, vr180 |
cursor | string | -- | Pagination cursor from a prior next_cursor |
Legacy boolean flags (subtitles, creative_commons, hd, 4k, live, 360, 3d, hdr, vr180) are still accepted for backward compatibility; prefer the features array.
Shorts (/shorts)
search* , sort_by, cursor.
Suggestions (/suggestions)
search* , language (default en), region (default US).
Video (/video) and metadata alias
video_id* — accepts a raw ID or a full watch URL.
Comments (/comments)
video_id* , cursor.
Comment replies (/comments/replies)
video_id* , reply_cursor* (a comment's reply_cursor), cursor.
Transcript (/transcript)
video_id* , language (default en), format (text for plain, srt for timed; default text).
Related (/related)
video_id* , cursor.
Streams (/streams)
video_id* .
Channel search (/channel/search)
search* , cursor.
Channel (/channel)
channel_id* — accepts a channel ID, @handle, or channel URL.
Channel videos / shorts / community
channel_id* , cursor.
Channel resolve (/channel/resolve)
channel* — a @handle or channel URL. Returns channel_id and channel_url.
Community post (/community/post)
post_id* — a community post id (post_id from /channel/community) or a post URL.
Community post comments (/community/post/comments)
post_id* , cursor (a prior next_cursor, or comments_cursor from /community/post).
Examples
import requests
BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# 1. Search — use "search" field, not "query"
search = requests.post(f"{BASE}/api/v1/youtube/search", headers=HEADERS,
json={"search": "langchain tutorial", "type": "video", "sort_by": "view_count"}).json()
video_id = search["data"]["results"][0]["video_id"]
# 2. Full video metadata (captions list included)
video = requests.post(f"{BASE}/api/v1/youtube/video", headers=HEADERS,
json={"video_id": video_id}).json()
# 3. Transcript as plain text
transcript = requests.post(f"{BASE}/api/v1/youtube/transcript", headers=HEADERS,
json={"video_id": video_id, "language": "en", "format": "text"}).json()
# 4. Resolve a handle, then pull the channel's videos
resolved = requests.post(f"{BASE}/api/v1/youtube/channel/resolve", headers=HEADERS,
json={"channel": "@freecodecamp"}).json()
channel_id = resolved["data"]["channel_id"]
videos = requests.post(f"{BASE}/api/v1/youtube/channel/videos", headers=HEADERS,
json={"channel_id": channel_id}).json()
Response shapes
Every response uses the envelope { data, response_time, credits_used, credits_remaining }. Key data fields per endpoint:
- search —
results[](type,video_id,title,url,description_snippet,thumbnail,duration_text,view_count,published_time,channel{id,name,url}), plusshorts,channels,playlists,next_cursor,has_more. - shorts —
results[](video_id,title,url,thumbnail,view_count,published_time,author,channel_id),next_cursor,has_more. - suggestions —
suggestions[](strings),total_count. - video —
video_id,title,author,channel_id,channel_url,published_at,description,length_seconds,view_count,keywords[],thumbnail,playability_status,chapters,captions[](language_code,language_name,url). - comments —
comments[](comment_id,text,like_count,reply_count,published_time,reply_cursor,author{channel_id,name,url,avatar,is_verified,is_creator}),next_cursor,has_more. - comments/replies —
replies[](same item shape as a comment),next_cursor,has_more. - transcript —
video_id,language_code,language_name,format,content. - related —
results[](video_id,title,url,author,channel_id,channel_url,thumbnail,view_count,published_time,length_seconds),total_count. - channel/search —
results[](channel_id,name,handle,url,thumbnail,subscriber_count,description,verified),next_cursor,has_more,total_count. - channel —
channel_id,title,description,handle,url,subscriber_count,video_count,view_count,country,creation_date,verified,has_business_email,avatar,banner,links[]. - channel/videos —
channel_id,results[](video_id,title,url,thumbnail,duration_text,view_count,published_time,is_live),next_cursor,has_more. - channel/shorts —
channel_id,results[](video_id,title,url,thumbnail,view_count),next_cursor,has_more,total_count. - channel/community —
channel_id,posts[](post_id,url,text,author_name,author_channel_id,published_time,vote_count,comment_count,images[],attachment_type),next_cursor,has_more. - channel/resolve —
channel_id,channel_url. - community/post —
post_id,url,text,author_name,author_channel_id,author_url,author_avatar,published_time,vote_count,comment_count(can be null),attachment_type,images[],comments_cursor. - community/post/comments —
comments[](comment_id,text,like_count,reply_count,published_time,reply_cursor,author{channel_id,name,url,avatar,is_verified,is_creator}),next_cursor,has_more. - streams —
video_id,title,author,length_seconds,view_count,is_live,formats[],adaptive_formats[],available_qualities[],expires_in_seconds.
{
"data": {
"results": [
{
"type": "video",
"video_id": "sVcwVQRHIc8",
"title": "Learn RAG From Scratch - Python AI Tutorial",
"url": "https://www.youtube.com/watch?v=sVcwVQRHIc8",
"duration_text": "2:33:11",
"view_count": 1258310,
"published_time": "1 year ago",
"thumbnail": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg",
"channel": { "id": "UC8butISFwT-Wl7EV0hUK0BQ", "name": "freeCodeCamp.org", "url": "https://www.youtube.com/@freecodecamp" }
}
],
"next_cursor": "EpMD...",
"has_more": true
},
"credits_used": 2,
"credits_remaining": 998
}
Guardrails
- The search parameter is
search, notquery— this is different from other Scavio endpoints. - Credits are not uniform:
searchandshortscost 2,streamscosts 3,transcriptcosts 5, and every other endpoint costs 1. Inform the user before paginating through many pages, especially transcripts. /metadatais a deprecated alias of/video; use/videoin new code.- Stream URLs from
/streamsexpire (expires_in_seconds) — use them promptly. - Never fabricate video IDs, view counts, transcripts, comments, or channel data. Only return API data.
Failure handling
400means an invalid parameter (e.g. a missingvideo_idorchannel_id) — fix and retry.401means the API key is invalid or missing. CheckSCAVIO_API_KEY.429means rate or usage limit exceeded. Wait before retrying. See rate limits.502/503mean upstream is temporarily unavailable. Wait a few seconds before retrying.- If search returns no results, suggest different keywords or relaxing filters.
- If a transcript is unavailable in the requested
language, retry withlanguage: enor check/videocaptions[]for available languages. - If
SCAVIO_API_KEYis not set, prompt the user to export it before continuing.
LangChain
pip install langchain-scavio==4.0.2
from langchain_scavio import ScavioSearchTool
tool = ScavioSearchTool(engine="youtube")
Related skills
- Downloads
- 843All time
- Security audit
- Pass
- Last updated
- 1mo ago
- Current version
- v1.0.4
- License
- MIT-0
