YouTube API
The YouTube API lets you search YouTube and retrieve video metadata through a single unified interface. Each endpoint returns structured JSON with credit usage tracking.
Endpoints
| Endpoint | Description |
|---|---|
POST /api/v1/youtube/search | Search YouTube with filters (date, duration, type, quality) |
POST /api/v1/youtube/metadata | Get structured metadata for a video (views, likes, tags, description) |
Authentication
| Header | Value | Required |
|---|---|---|
Authorization | Bearer YOUR_API_KEY | Yes |
Content-Type | application/json | Yes |
YouTube Search
Bash
POST https://api.scavio.dev/api/v1/youtube/searchSearch YouTube and get structured results. Supports filtering by upload date, duration, result type, video quality, and more.
Request Body
| Parameter | Type | Default | Description |
|---|---|---|---|
search | string | -- | Required. Search query (1-500 chars). |
upload_date | string | -- | Filter by upload date. One of: last_hour, today, this_week, this_month, this_year |
type | string | -- | Filter by result type. One of: video, channel, playlist |
duration | string | -- | Filter by video duration. One of: short (under 4 min), medium (4-20 min), long (over 20 min) |
sort_by | string | relevance | Sort order. One of: relevance, date, view_count, rating |
hd | boolean | false | HD videos only |
4k | boolean | false | 4K videos only |
subtitles | boolean | false | Videos with subtitles/captions only |
creative_commons | boolean | false | Creative Commons licensed videos only |
live | boolean | false | Live streams only |
hdr | boolean | false | HDR videos only |
360 | boolean | false | 360-degree videos only |
3d | boolean | false | 3D videos only |
location | boolean | false | Videos with location metadata only |
vr180 | boolean | false | VR180 videos only |
Example
curl -X POST 'https://api.scavio.dev/api/v1/youtube/search' \
-H 'Authorization: Bearer sk_live_your_key' \
-H 'Content-Type: application/json' \
-d '{
"search": "langchain tutorial",
"type": "video",
"duration": "medium",
"sort_by": "view_count",
"upload_date": "this_year"
}'Response Example
JSON
{
"data": {
"results": [
{
"videoId": "sVcwVQRHIc8",
"title": { "runs": [{ "text": "Learn RAG From Scratch - Python AI Tutorial" }] },
"longBylineText": { "runs": [{ "text": "freeCodeCamp.org" }] },
"publishedTimeText": { "simpleText": "1 year ago" },
"lengthText": { "simpleText": "2:33:11" },
"viewCountText": { "simpleText": "1,258,310 views" },
"thumbnail": { "thumbnails": [{ "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg", "width": 360, "height": 202 }] }
}
],
"search": "langchain tutorial"
},
"response_time": 1230,
"credits_used": 1,
"credits_remaining": 999
}Video Metadata
Bash
POST https://api.scavio.dev/api/v1/youtube/metadataGet structured metadata for a YouTube video including title, description, view count, like count, comment count, tags, thumbnails, upload date, channel info, and available formats.
Request Body
| Parameter | Type | Description |
|---|---|---|
video_id | string | Required. YouTube video ID (e.g. dQw4w9WgXcQ). |
Example
curl -X POST 'https://api.scavio.dev/api/v1/youtube/metadata' \
-H 'Authorization: Bearer sk_live_your_key' \
-H 'Content-Type: application/json' \
-d '{"video_id": "sVcwVQRHIc8"}'Response Example
JSON
{
"data": {
"title": "Learn RAG From Scratch - Python AI Tutorial",
"description": "Learn how to implement RAG from scratch...",
"upload_date": 20240417,
"duration": 9191,
"view_count": 1258310,
"like_count": 23211,
"comment_count": 295,
"categories": ["Education"],
"tags": ["rag", "langchain", "python", "llm"],
"channel_id": "UC8butISFwT-Wl7EV0hUK0BQ",
"channel_url": "https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ",
"uploader": "freeCodeCamp.org",
"uploader_id": "@freecodecamp",
"uploader_url": "https://www.youtube.com/@freecodecamp",
"video_id": "sVcwVQRHIc8",
"is_live": false,
"age_limit": 0,
"thumbnails": [
{
"url": "https://i.ytimg.com/vi/sVcwVQRHIc8/maxresdefault.jpg",
"width": 1280,
"height": 720
}
],
"formats": []
},
"response_time": 890,
"credits_used": 1,
"credits_remaining": 998
}Response Format
All YouTube endpoints return a consistent response wrapper:
| Field | Type | Description |
|---|---|---|
data | object | null | The response payload. Shape depends on the endpoint. Search returns {results, search}; metadata returns the video object. null if the request failed upstream. |
response_time | number | Server-side response time in milliseconds |
credits_used | number | Number of credits consumed by this request |
credits_remaining | number | Credits remaining in your current billing period |
Error Responses
| Status | Description |
|---|---|
401 | Unauthorized -- missing or invalid API key |
429 | Rate or usage limit exceeded for your plan |
502 | Upstream error -- retry after a short delay |
503 | Upstream unavailable -- retry later |
See Errors for the full error reference and retry best practices.
Related
- Quickstart -- get your API key and make your first request
- Google Search API -- search Google with structured SERP data
- Amazon API -- search products and get details by ASIN
- Rate Limits -- limits per plan tier
- Errors -- error codes and handling