{ "openapi": "3.1.0", "info": { "title": "YouTubeAPI.io — Real-Time YouTube Transcript, Comments, Video Metadata, Search & Channel API", "version": "1.0.0", "description": "High-throughput REST API for extracting timestamped YouTube transcripts, video metadata, top/newest comments, video/Shorts search, and creator channel feeds for AI Agents, RAG pipelines, and analytics. Authenticate via `x-api-key: yt_live_...` or `Authorization: Bearer yt_live_...`. Pricing anchor: $1 = 10,000 Credits (10 Credits = $0.001 per lookup/transcript call; 1 Credit per list item with 10 Credits minimum floor; 0 Credits on 4xx/5xx/empty).", "contact": { "name": "YouTubeAPI.io Engineering", "email": "contact@youtubeapi.io", "url": "https://youtubeapi.io" } }, "servers": [ { "url": "https://api.youtubeapi.io", "description": "Production API Gateway" } ], "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your YouTubeAPI.io API key (e.g. `yt_live_...`)." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Pass your API key as `Authorization: Bearer yt_live_...`." } }, "schemas": { "ResponseMeta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique UUID for tracing and support." }, "endpoint": { "type": "string", "description": "Canonical endpoint path." }, "cached": { "type": "boolean", "description": "True if served from L1 Redis or L2 PostgreSQL 16 asset sink." }, "source": { "type": "string", "description": "Data source tier (`redis`, `pg`, `upstream_primary`, `upstream_fallback`, `oembed`)." }, "items_count": { "type": "integer", "description": "Number of records returned in `data`." }, "credits_charged": { "type": "integer", "description": "Credits deducted for this request ($1 = 10,000 Credits)." }, "has_more": { "type": "boolean", "description": "Whether additional pages are available via `next_cursor`." }, "next_cursor": { "type": ["string", "null"], "description": "Continuation cursor for the next page." }, "latency_ms": { "type": "integer", "description": "End-to-end gateway latency in milliseconds." } } }, "TranscriptSegment": { "type": "object", "properties": { "text": { "type": "string", "description": "Decoded plain-text caption segment." }, "startSec": { "type": "number", "description": "Segment start timestamp in seconds." }, "durationSec": { "type": "number", "description": "Segment duration in seconds." }, "endSec": { "type": "number", "description": "Segment end timestamp in seconds." } } }, "TranscriptData": { "type": "object", "properties": { "videoId": { "type": "string", "description": "11-character YouTube video ID." }, "url": { "type": "string", "description": "Canonical YouTube watch URL." }, "title": { "type": "string", "description": "Video title." }, "channelId": { "type": "string", "description": "YouTube channel ID (`UC...`)." }, "channelTitle": { "type": "string", "description": "Channel display name." }, "language": { "type": "string", "description": "Selected transcript language code (e.g. `en`)." }, "languageLabel": { "type": "string", "description": "Human-readable language name (e.g. `English`)." }, "isAutoGenerated": { "type": "boolean", "description": "True if auto-generated ASR track." }, "isTranslatable": { "type": "boolean", "description": "Whether YouTube supports auto-translation for this track." }, "availableLanguages": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "isAutoGenerated": { "type": "boolean" } } } }, "segmentsCount": { "type": "integer", "description": "Total number of timed caption segments." }, "totalDurationSec": { "type": "number", "description": "Total duration covered by transcript in seconds." }, "wordCount": { "type": "integer", "description": "Word count of `fullTranscriptText`." }, "fullTranscriptText": { "type": "string", "description": "Concatenated plain-text transcript ready for LLM/RAG ingestion." }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptSegment" } } } }, "VideoData": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["video", "short", "live"] }, "videoId": { "type": "string", "description": "11-character YouTube video ID." }, "videoType": { "type": "string", "enum": ["video", "short", "live"] }, "url": { "type": "string", "description": "Canonical YouTube video or Shorts URL." }, "title": { "type": "string", "description": "Video title." }, "description": { "type": "string", "description": "Full video description including timestamps and links." }, "channelId": { "type": "string", "description": "Channel ID (`UC...`)." }, "channelTitle": { "type": "string", "description": "Channel display name." }, "channelHandle": { "type": ["string", "null"], "description": "Channel handle without `@` (e.g. `mrbeast`)." }, "lengthSeconds": { "type": "integer", "description": "Video duration in seconds." }, "viewCount": { "type": "integer", "description": "Total view count." }, "likeCount": { "type": "integer", "description": "Total like count." }, "commentCount": { "type": "integer", "description": "Total comment count." }, "publishDate": { "type": ["string", "null"], "description": "ISO 8601 publish timestamp." }, "publishedText": { "type": ["string", "null"], "description": "Relative or formatted publish date text." }, "category": { "type": ["string", "null"], "description": "YouTube video category." }, "isLiveContent": { "type": "boolean" }, "isShort": { "type": "boolean" }, "isFamilySafe": { "type": "boolean" }, "thumbnailUrl": { "type": ["string", "null"], "description": "High-resolution thumbnail URL." }, "keywords": { "type": "array", "items": { "type": "string" } }, "hasTranscript": { "type": "boolean", "description": "True if captions/transcripts are available." } } }, "CommentData": { "type": "object", "properties": { "commentId": { "type": "string", "description": "Unique YouTube comment ID." }, "videoId": { "type": "string", "description": "11-character YouTube video ID." }, "parentId": { "type": ["string", "null"], "description": "Parent comment ID if reply." }, "author": { "type": "string", "description": "Author handle or display name." }, "authorChannelId": { "type": ["string", "null"], "description": "Author's YouTube channel ID." }, "authorAvatar": { "type": ["string", "null"], "description": "Author profile image URL." }, "authorIsOwner": { "type": "boolean", "description": "True if comment is by the video creator." }, "authorIsVerified": { "type": "boolean" }, "text": { "type": "string", "description": "Comment text content." }, "likeCount": { "type": "integer", "description": "Number of likes on the comment." }, "replyCount": { "type": "integer", "description": "Number of replies to the comment." }, "isHearted": { "type": "boolean", "description": "True if hearted by the creator." }, "isPinned": { "type": "boolean", "description": "True if pinned to top of comments." }, "publishedTimeText": { "type": ["string", "null"], "description": "Relative publish time (e.g. `2 days ago`)." }, "publishedAt": { "type": ["string", "null"], "description": "ISO 8601 timestamp when available." } } }, "ChannelData": { "type": "object", "properties": { "channelId": { "type": "string", "description": "YouTube channel ID (`UC...`)." }, "handle": { "type": ["string", "null"], "description": "Lowercase channel handle without `@`." }, "title": { "type": "string", "description": "Channel title." }, "description": { "type": "string", "description": "Full channel about description." }, "subscriberCount": { "type": "integer", "description": "Parsed integer subscriber count." }, "subscriberText": { "type": "string", "description": "Formatted subscriber count string (e.g. `345M subscribers`)." }, "videosCount": { "type": "integer", "description": "Total public videos count." }, "viewCount": { "type": "integer", "description": "Total channel lifetime views." }, "country": { "type": ["string", "null"], "description": "Channel country code." }, "joinedDate": { "type": ["string", "null"], "description": "Channel creation date." }, "avatarUrl": { "type": ["string", "null"], "description": "Channel avatar image URL." }, "bannerUrl": { "type": ["string", "null"], "description": "Channel banner image URL." }, "isVerified": { "type": "boolean", "description": "Whether the channel has a verification badge." }, "keywords": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" } } } }, "url": { "type": "string", "description": "Canonical YouTube channel URL." } } } } }, "paths": { "/v1/youtube/transcript": { "get": { "operationId": "v1_youtube_transcript", "summary": "Extract Timestamped YouTube Video Transcript & Full RAG Text", "description": "Fetches full plain-text transcript (`fullTranscriptText`), word count, available subtitle languages, and millisecond-accurate timestamped segments (`segments`) for any YouTube video or Short. Cost: **10 Credits** ($0.001) per video.", "tags": ["Transcripts & Captions"], "parameters": [ { "name": "video_id", "in": "query", "required": true, "description": "11-character YouTube video ID (`dQw4w9WgXcQ`) or full YouTube watch/Shorts URL (`https://www.youtube.com/watch?v=dQw4w9WgXcQ`). Also accepts `id`, `videoId`, or `url`.", "schema": { "type": "string", "default": "dQw4w9WgXcQ" } }, { "name": "lang", "in": "query", "required": false, "description": "Preferred ISO 639-1 language code (`en`, `es`, `de`, `fr`, `ja`, `zh-Hans`, etc.). Defaults to `en` with automatic fallback to the primary available track.", "schema": { "type": "string", "default": "en" } }, { "name": "include_segments", "in": "query", "required": false, "description": "Set to `false` to omit the `segments` array and return only `fullTranscriptText` for lightweight LLM context windows.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Successful transcript response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "provider": { "type": "string", "example": "https://youtubeapi.io" }, "status": { "type": "string", "example": "ok" }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/TranscriptData" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "example": { "code": 0, "provider": "https://youtubeapi.io", "status": "ok", "msg": "success", "data": { "videoId": "dQw4w9WgXcQ", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw", "channelTitle": "Rick Astley", "language": "en", "languageLabel": "English", "isAutoGenerated": false, "isTranslatable": true, "availableLanguages": [ { "code": "en", "name": "English", "isAutoGenerated": false }, { "code": "es", "name": "Spanish", "isAutoGenerated": false } ], "segmentsCount": 8, "totalDurationSec": 53.6, "wordCount": 68, "fullTranscriptText": "We're no strangers to love You know the rules and so do I A full commitment's what I'm thinking of You wouldn't get this from any other guy I just wanna tell you how I'm feeling Gotta make you understand Never gonna give you up Never gonna let you down Never gonna run around and desert you Never gonna make you cry Never gonna say goodbye", "segments": [ { "text": "We're no strangers to love", "startSec": 18.6, "durationSec": 3.72, "endSec": 22.32 }, { "text": "You know the rules and so do I", "startSec": 22.32, "durationSec": 4.44, "endSec": 26.76 } ] }, "meta": { "request_id": "9f8c2b10-6112-4a2b-9d1a-8f42ed904989", "endpoint": "/v1/youtube/transcript", "cached": true, "source": "pg", "items_count": 1, "credits_charged": 10, "latency_ms": 6 } } } } } } } }, "/v1/youtube/video": { "get": { "operationId": "v1_youtube_video", "summary": "Get Full YouTube Video or Shorts Metadata & Engagement Stats", "description": "Returns rich video metadata including title, full description, views, likes, comment count, duration, publish timestamp, tags/keywords, channel info, and caption availability. Cost: **10 Credits** ($0.001) per video.", "tags": ["Videos & Shorts"], "parameters": [ { "name": "video_id", "in": "query", "required": true, "description": "11-character YouTube video ID (`dQw4w9WgXcQ`) or full YouTube URL. Also accepts `id`, `videoId`, or `url`.", "schema": { "type": "string", "default": "dQw4w9WgXcQ" } } ], "responses": { "200": { "description": "Successful video metadata response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "provider": { "type": "string", "example": "https://youtubeapi.io" }, "status": { "type": "string", "example": "ok" }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/VideoData" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "example": { "code": 0, "provider": "https://youtubeapi.io", "status": "ok", "msg": "success", "data": { "kind": "video", "videoId": "dQw4w9WgXcQ", "videoType": "video", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "description": "The official video for “Never Gonna Give You Up” by Rick Astley.", "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw", "channelTitle": "Rick Astley", "channelHandle": "rickastleyyt", "lengthSeconds": 213, "viewCount": 1618420000, "likeCount": 18100000, "commentCount": 2410000, "publishDate": "2009-10-25T06:57:33.000Z", "publishedText": "2009-10-25", "category": "Music", "isLiveContent": false, "isShort": false, "isFamilySafe": true, "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", "keywords": ["rick astley", "never gonna give you up", "80s music"], "hasTranscript": true }, "meta": { "request_id": "1a2b3c4d-1111-2222-3333-444455556666", "endpoint": "/v1/youtube/video", "cached": true, "source": "pg", "items_count": 1, "credits_charged": 10, "latency_ms": 5 } } } } } } } }, "/v1/youtube/comments": { "get": { "operationId": "v1_youtube_comments", "summary": "Fetch Paginated YouTube Video Comments (Top or Newest)", "description": "Retrieves top or newest comments for a YouTube video, including author handle, channel ID, like count, reply count, pinned/hearted badges, and `nextCursor` pagination token. Cost: **1 Credit per comment returned** (minimum 10 Credits per non-empty call).", "tags": ["Comments & Sentiment"], "parameters": [ { "name": "video_id", "in": "query", "required": true, "description": "11-character YouTube video ID (`dQw4w9WgXcQ`) or full YouTube URL.", "schema": { "type": "string", "default": "dQw4w9WgXcQ" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order: `top` (most relevant/liked) or `newest`.", "schema": { "type": "string", "enum": ["top", "newest"], "default": "top" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of comments to return per page (1–100).", "schema": { "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Continuation token from `data.nextCursor` (`meta.next_cursor`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful comments response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "provider": { "type": "string" }, "status": { "type": "string" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "videoId": { "type": "string" }, "totalCommentsCount": { "type": "integer" }, "sortBy": { "type": "string" }, "nextCursor": { "type": ["string", "null"] }, "continuation": { "type": ["string", "null"] }, "hasMore": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CommentData" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "example": { "code": 0, "provider": "https://youtubeapi.io", "status": "ok", "msg": "success", "data": { "videoId": "dQw4w9WgXcQ", "totalCommentsCount": 2410000, "sortBy": "top", "nextCursor": null, "continuation": null, "hasMore": false, "items": [ { "commentId": "UgzX_dQw4w9WgXcQ_1", "videoId": "dQw4w9WgXcQ", "parentId": null, "author": "@YouTube", "authorChannelId": "UCBR8-60-B28hp2BmDPdntcQ", "authorAvatar": null, "authorIsOwner": false, "authorIsVerified": true, "text": "Can confirm: he never gave us up.", "likeCount": 942000, "replyCount": 512, "isHearted": true, "isPinned": true, "publishedTimeText": "3 years ago", "publishedAt": "2023-01-15T12:00:00.000Z" } ] }, "meta": { "request_id": "2b3c4d5e-2222-3333-4444-555566667777", "endpoint": "/v1/youtube/comments", "cached": true, "source": "pg", "items_count": 2, "credits_charged": 10, "has_more": false, "next_cursor": null, "latency_ms": 7 } } } } } } } }, "/v1/youtube/search": { "get": { "operationId": "v1_youtube_search", "summary": "Search YouTube Videos & Shorts by Keyword & Filters", "description": "Searches YouTube videos and Shorts without the 100-unit quota penalty of official YouTube Data API v3 `search.list`. Supports filtering by `type` (`video` or `shorts`), `sort_by` (`relevance`, `date`, `views`, `rating`), `upload_date`, and `duration`. Cost: **1 Credit per item returned** (minimum 10 Credits per non-empty call).", "tags": ["Search & Discovery"], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query string (also accepts `q` or `keyword`).", "schema": { "type": "string", "default": "ai agents" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by content type: `video` or `shorts`.", "schema": { "type": "string", "enum": ["video", "shorts"], "default": "video" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order: `relevance`, `date`, `views`, or `rating`.", "schema": { "type": "string", "enum": ["relevance", "date", "views", "rating"], "default": "relevance" } }, { "name": "upload_date", "in": "query", "required": false, "description": "Filter by upload timeframe: `hour`, `today`, `week`, `month`, `year`.", "schema": { "type": "string", "enum": ["hour", "today", "week", "month", "year"] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return (1–100).", "schema": { "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Continuation cursor for next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "provider": { "type": "string" }, "status": { "type": "string" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "query": { "type": "string" }, "type": { "type": "string" }, "sortBy": { "type": "string" }, "nextCursor": { "type": ["string", "null"] }, "continuation": { "type": ["string", "null"] }, "hasMore": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VideoData" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "example": { "code": 0, "provider": "https://youtubeapi.io", "status": "ok", "msg": "success", "data": { "query": "youtube api", "type": "video", "sortBy": "relevance", "nextCursor": null, "continuation": null, "hasMore": false, "items": [ { "kind": "video", "videoId": "M7lc1UVf-VE", "videoType": "video", "url": "https://www.youtube.com/watch?v=M7lc1UVf-VE", "title": "YouTube Developers Live: Embedded Web Player Customization", "description": "Learn how to customize the YouTube IFrame Player API.", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "channelTitle": "Google for Developers", "channelHandle": "googledevelopers", "lengthSeconds": 1340, "viewCount": 1945200, "likeCount": 14500, "commentCount": 980, "publishDate": "2013-05-15T18:00:00.000Z", "publishedText": "2013-05-15", "category": "Science & Technology", "isLiveContent": false, "isShort": false, "isFamilySafe": true, "thumbnailUrl": "https://i.ytimg.com/vi/M7lc1UVf-VE/hqdefault.jpg", "keywords": ["youtube api", "google developers"], "hasTranscript": true } ] }, "meta": { "request_id": "3c4d5e6f-3333-4444-5555-666677778888", "endpoint": "/v1/youtube/search", "cached": true, "source": "pg", "items_count": 1, "credits_charged": 10, "has_more": false, "next_cursor": null, "latency_ms": 8 } } } } } } } }, "/v1/youtube/channel": { "get": { "operationId": "v1_youtube_channel", "summary": "Get YouTube Channel Profile, Subscriber Count & Social Links", "description": "Resolves a YouTube channel by `@handle`, `UC...` channel ID, or full URL and returns subscriber count, total lifetime views, video count, verification status, country, keywords, and external links. Cost: **10 Credits** ($0.001) per call.", "tags": ["Channels & Creators"], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "YouTube channel handle (e.g. `@MrBeast`, `mrbeast`, or `@googledevelopers`). Provide either `handle`, `channel_id`, or `url`.", "schema": { "type": "string", "default": "@MrBeast" } }, { "name": "channel_id", "in": "query", "required": false, "description": "YouTube channel ID starting with `UC` (e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful channel profile response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "provider": { "type": "string" }, "status": { "type": "string" }, "msg": { "type": "string" }, "data": { "$ref": "#/components/schemas/ChannelData" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "example": { "code": 0, "provider": "https://youtubeapi.io", "status": "ok", "msg": "success", "data": { "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "handle": "mrbeast", "title": "MrBeast", "description": "SUBSCRIBE FOR A COOKIE!", "subscriberCount": 345000000, "subscriberText": "345M subscribers", "videosCount": 842, "viewCount": 68500000000, "country": "US", "joinedDate": "Feb 19, 2012", "avatarUrl": "https://yt3.googleusercontent.com/fxGKYucJAVme-Yz4fsdCroCFCrANWqw0ql4GYuvx8Uq4l_euNJHgE-w9MTkLQA805vWCi-kE0g=s176-c-k-c0x00ffffff-no-rj", "bannerUrl": null, "isVerified": true, "keywords": ["mrbeast", "challenge", "philanthropy"], "links": [{ "title": "Shop MrBeast", "url": "https://mrbeast.store" }], "url": "https://www.youtube.com/@mrbeast" }, "meta": { "request_id": "4d5e6f70-4444-5555-6666-777788889999", "endpoint": "/v1/youtube/channel", "cached": true, "source": "pg", "items_count": 1, "credits_charged": 10, "latency_ms": 5 } } } } } } } }, "/v1/youtube/channel/videos": { "get": { "operationId": "v1_youtube_channel_videos", "summary": "List a YouTube Channel's Uploaded Videos Feed", "description": "Returns paginated long-form videos uploaded by a channel, sorted by `newest`, `popular`, or `oldest`. Cost: **1 Credit per video returned** (minimum 10 Credits per non-empty call).", "tags": ["Channels & Creators"], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "YouTube channel handle (e.g. `@googledevelopers`). Provide `handle` or `channel_id`.", "schema": { "type": "string", "default": "@googledevelopers" } }, { "name": "channel_id", "in": "query", "required": false, "description": "YouTube channel ID (`UC_x5XG1OV2P6uZZ5FSM9Ttw`).", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order: `newest`, `popular`, or `oldest`.", "schema": { "type": "string", "enum": ["newest", "popular", "oldest"], "default": "newest" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 30 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful channel videos feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "provider": { "type": "string" }, "status": { "type": "string" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/ChannelData" }, "feedType": { "type": "string", "example": "videos" }, "sortBy": { "type": "string" }, "nextCursor": { "type": ["string", "null"] }, "continuation": { "type": ["string", "null"] }, "hasMore": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VideoData" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } } } } }, "/v1/youtube/channel/shorts": { "get": { "operationId": "v1_youtube_channel_shorts", "summary": "List a YouTube Channel's Shorts Feed", "description": "Returns paginated vertical Shorts uploaded by a YouTube channel, sorted by `newest` or `popular`. Cost: **1 Credit per Short returned** (minimum 10 Credits per non-empty call).", "tags": ["Channels & Creators"], "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "YouTube channel handle (e.g. `@MrBeast`). Provide `handle` or `channel_id`.", "schema": { "type": "string", "default": "@MrBeast" } }, { "name": "channel_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": ["newest", "popular"], "default": "newest" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 30 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful channel Shorts feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "provider": { "type": "string" }, "status": { "type": "string" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/ChannelData" }, "feedType": { "type": "string", "example": "shorts" }, "sortBy": { "type": "string" }, "nextCursor": { "type": ["string", "null"] }, "continuation": { "type": ["string", "null"] }, "hasMore": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VideoData" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } } } } }, "/v1/youtube/trending": { "get": { "operationId": "v1_youtube_trending", "summary": "Get Trending YouTube Videos by Country & Category", "description": "Fetches currently trending YouTube videos for a 2-letter ISO country code (`US`, `GB`, `JP`, `DE`, `IN`, etc.) and category (`now`, `music`, `gaming`, `movies`). Cost: **Flat 10 Credits** ($0.001) per call.", "tags": ["Search & Discovery"], "parameters": [ { "name": "geo", "in": "query", "required": false, "description": "2-letter ISO 3166-1 alpha-2 country code.", "schema": { "type": "string", "default": "US" } }, { "name": "type", "in": "query", "required": false, "description": "Trending category (`now`, `music`, `gaming`, `movies`).", "schema": { "type": "string", "enum": ["now", "music", "gaming", "movies"], "default": "now" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 30 } } ], "responses": { "200": { "description": "Successful trending videos response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "provider": { "type": "string" }, "status": { "type": "string" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "geo": { "type": "string" }, "category": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VideoData" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } } } } } } }