YouTube API

The YouTube API lets you search YouTube, retrieve video metadata, extract transcripts, and check trainability -- all 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)
`POST /api/v1/youtube/transcript`	Extract the transcript/captions for a video
`POST /api/v1/youtube/trainability`	Check if a video can be used for AI training (coming soon)

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/search

Search 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/metadata

Get 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
}

Video Transcript

Bash

POST https://api.scavio.dev
/api/v1/youtube/transcript

Extract the transcript (captions/subtitles) for a YouTube video. Supports multiple languages and both auto-generated and uploader-provided transcripts.

Request Body

Parameter	Type	Default	Description
`video_id`	`string`	--	Required. YouTube video ID.
`language`	`string`	`en`	Transcript language code (e.g. `en`, `es`, `fr`, `de`).
`transcript_origin`	`string`	--	Transcript origin. Use `auto_generated` for auto-captions or `uploader_provided` for manual captions.

Example

curl -X POST 'https://api.scavio.dev
/api/v1/youtube/transcript' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_id": "sVcwVQRHIc8",
    "language": "en"
  }'

Response Example

JSON

{
  "data": {
    "text": "in this course you will learn how to build retrieval augmented generation from scratch...",
    "transcripts": [
      {
        "text": "in this course you will learn how to build",
        "start": 0.0,
        "duration": 3.2
      },
      {
        "text": "retrieval augmented generation from scratch",
        "start": 3.2,
        "duration": 2.8
      },
      {
        "text": "straight from a LangChain software engineer",
        "start": 6.0,
        "duration": 3.1
      }
    ]
  },
  "response_time": 1450,
  "credits_used": 1,
  "credits_remaining": 997
}

Video Trainability

Bash

POST https://api.scavio.dev
/api/v1/youtube/trainability

Coming soon. This endpoint is not yet available.

When available, it will check if a YouTube video has transcripts available and is suitable for AI training purposes. Returns information about transcript availability, license, and training eligibility.

Request Body

Parameter	Type	Description
`video_id`	`string`	Required. YouTube video ID.

Example

curl -X POST 'https://api.scavio.dev
/api/v1/youtube/trainability' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"video_id": "sVcwVQRHIc8"}'

Response Example

JSON

{
  "data": {
    "video_id": "sVcwVQRHIc8",
    "has_transcript": true,
    "transcript_languages": ["en", "es", "fr", "de", "pt"],
    "license": "standard",
    "is_trainable": true
  },
  "response_time": 670,
  "credits_used": 1,
  "credits_remaining": 996
}

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}`; transcript returns `{text, transcripts}`; 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.

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

YouTube API

Endpoints

Authentication

YouTube Search

Request Body

Example

Response Example

Video Metadata

Request Body

Example

Response Example

Video Transcript

Request Body

Example

Response Example

Video Trainability

Request Body

Example

Response Example

Response Format

Error Responses

Related