{"openapi":"3.1.0","info":{"title":"Supadata","description":"Web & Social Media Content API for Developers","version":"1.3.0"},"servers":[{"url":"https://api.supadata.ai/v1"}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"YoutubeVideo":{"type":"object","properties":{"id":{"type":"string","description":"YouTube video ID","example":"dQw4w9WgXcQ"},"title":{"type":"string","description":"Video title","example":"Rick Astley - Never Gonna Give You Up (Official Music Video)"},"description":{"type":"string","description":"Video description","example":"The official music video for \"Never Gonna Give You Up\"..."},"duration":{"type":"number","description":"Video duration in seconds","example":213},"channel":{"type":"object","properties":{"id":{"type":"string","description":"Channel ID","example":"UCuAXFkgsw1L7xaCfnd5JJOw"},"name":{"type":"string","description":"Channel name","example":"Rick Astley"}},"required":["id","name"],"description":"Channel information"},"tags":{"type":"array","items":{"type":"string"},"description":"Video tags","example":["Rick Astley","Official Video","Music"]},"thumbnail":{"type":"string","description":"URL to video thumbnail","example":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"},"uploadDate":{"type":["string","null"],"description":"Video upload date","example":"2009-10-25T00:00:00.000Z","format":"date-time"},"viewCount":{"type":["number","null"],"description":"Number of views","example":1234567890},"likeCount":{"type":["number","null"],"description":"Number of likes","example":12345678},"transcriptLanguages":{"type":"array","items":{"type":"string"},"description":"Available transcript language codes","example":["en","es","fr"]}},"required":["id","title","description","duration","channel","tags","transcriptLanguages"]},"Error":{"type":"object","properties":{"error":{"type":"string","enum":["invalid-request","internal-error","forbidden","unauthorized","upgrade-required","transcript-unavailable","not-found","limit-exceeded"],"description":"Error code identifying the type of error","example":"invalid-request"},"message":{"type":"string","description":"Human readable error message","example":"Invalid Request"},"details":{"type":"string","description":"Detailed error description","example":"The request is invalid or malformed"},"documentationUrl":{"type":"string","description":"URL to error documentation","example":"https://docs.supadata.ai/errors#invalid-request"}},"required":["error","message","details"],"description":"Standard error response format"},"YoutubePlaylist":{"type":"object","properties":{"id":{"type":"string","description":"YouTube playlist ID","example":"PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc"},"title":{"type":"string","description":"Playlist title","example":"My Favorite Videos"},"description":{"type":"string","description":"Playlist description","example":"A collection of my favorite videos"},"videoCount":{"type":"number","description":"Number of videos in the playlist","example":25},"viewCount":{"type":"number","description":"Number of views for the playlist","example":1000000},"lastUpdated":{"type":"string","description":"When the playlist was last updated","example":"2023-01-01T00:00:00.000Z","format":"date-time"},"channel":{"type":"object","properties":{"id":{"type":"string","description":"Channel ID","example":"UCuAXFkgsw1L7xaCfnd5JJOw"},"name":{"type":"string","description":"Channel name","example":"Rick Astley"}},"required":["id","name"],"description":"Channel information"}},"required":["id","title","videoCount","channel"]},"VideoIds":{"type":"object","properties":{"videoIds":{"type":"array","items":{"type":"string"},"description":"List of vertical video IDs","example":["dQw4w9WgXcQ","xvFZjo5PgG0"]},"shortIds":{"type":"array","items":{"type":"string"},"description":"List of Shorts IDs","example":["dQw4w9WgXcQ","xvFZjo5PgG0"]},"liveIds":{"type":"array","items":{"type":"string"},"description":"List of live video IDs","example":["dQw4w9WgXcQ","xvFZjo5PgG0"]}},"required":["videoIds","shortIds","liveIds"]},"YoutubeChannel":{"type":"object","properties":{"id":{"type":"string","description":"YouTube channel ID","example":"UCuAXFkgsw1L7xaCfnd5JJOw"},"name":{"type":"string","description":"Channel name","example":"Rick Astley"},"description":{"type":"string","description":"Channel description","example":"The official Rick Astley YouTube channel"},"subscriberCount":{"type":"number","description":"Number of subscribers","example":2000000},"videoCount":{"type":"number","description":"Number of videos on the channel","example":100},"viewCount":{"type":"number","description":"Total number of views across all channel videos","example":1002293434},"thumbnail":{"type":"string","description":"URL to channel thumbnail","example":"https://yt3.ggpht.com/..."},"banner":{"type":"string","description":"URL to channel banner","example":"https://yt3.ggpht.com/..."}},"required":["id","name"]},"Transcript":{"type":"object","properties":{"content":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/TranscriptChunk"}},{"type":"string","description":"Plain text transcript when text=true parameter is used","example":"Never gonna give you up, never gonna let you down..."}]},"lang":{"type":"string","description":"ISO 639-1 language code of transcript","example":"en"},"availableLangs":{"type":"array","items":{"type":"string"},"description":"List of available language codes","example":["en","es","zh-TW"]}},"required":["content","lang","availableLangs"]},"TranscriptChunk":{"type":"object","properties":{"text":{"type":"string","description":"Transcript segment","example":"Never gonna give you up..."},"offset":{"type":"number","description":"Start time in milliseconds","example":8150},"duration":{"type":"number","description":"Duration in milliseconds","example":1200},"lang":{"type":"string","description":"ISO 639-1 language code of chunk","example":"en"}},"required":["text","offset","duration"]},"TranslatedTranscript":{"type":"object","properties":{"content":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/TranscriptChunk"}},{"type":"string","description":"Plain text transcript when text=true parameter is used","example":"Nunca voy a abandonarte, nunca voy a decepcionarte…"}]},"lang":{"type":"string","description":"ISO 639-1 language code of translation","example":"es"}},"required":["content","lang"]},"JobId":{"type":"object","properties":{"jobId":{"type":"string","description":"The ID of the job","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["jobId"]},"YouTubeBatchResults":{"type":"object","properties":{"status":{"type":"string","enum":["queued","active","completed","failed"],"description":"Current status of the batch job","example":"completed"},"results":{"type":"array","items":{"type":"object","properties":{"videoId":{"type":"string","description":"YouTube video ID","example":"dQw4w9WgXcQ"},"transcript":{"oneOf":[{"$ref":"#/components/schemas/Transcript"},{"type":"null"}]},"video":{"oneOf":[{"$ref":"#/components/schemas/YoutubeVideo"},{"type":"null"}]},"errorCode":{"type":["string","null"],"enum":["invalid-request","internal-error","forbidden","unauthorized","upgrade-required","transcript-unavailable","not-found","limit-exceeded"],"description":"Error code if processing this item failed","example":"not-found"}},"required":["videoId"]},"description":"Array of results for each video in the batch"},"stats":{"type":"object","properties":{"total":{"type":"number","description":"Total number of items in the batch","example":10},"succeeded":{"type":"number","description":"Number of items successfully processed","example":8},"failed":{"type":"number","description":"Number of items that failed processing","example":2}},"required":["total","succeeded","failed"],"description":"Statistics about the batch job progress"},"completedAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the job completed, if status is completed","example":"2025-04-03T06:59:53.428Z"}},"required":["status","results","stats"],"description":"Response for batch job results"},"YoutubeSearch":{"type":"object","properties":{"query":{"type":"string","description":"The search query that was executed","example":"Rick Astley Never Gonna Give You Up"},"results":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["video","channel","playlist"],"description":"Type of the search result","example":"video"},"id":{"type":"string","description":"ID of the video, channel, or playlist","example":"dQw4w9WgXcQ"},"title":{"type":"string","description":"Title of the result","example":"Rick Astley - Never Gonna Give You Up (Official Video)"},"description":{"type":"string","description":"Description of the result","example":"The official music video for Rick Astley..."},"thumbnail":{"type":"string","description":"URL to the thumbnail image","example":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"},"duration":{"type":"number","description":"Duration in seconds (for videos only)","example":213},"viewCount":{"type":"number","description":"View count (for videos only)","example":1234567890},"uploadDate":{"type":"string","description":"Upload date (for videos only)","example":"2009-10-25T00:00:00.000Z","format":"date-time"},"channel":{"type":"object","properties":{"id":{"type":"string","description":"Channel ID","example":"UCuAXFkgsw1L7xaCfnd5JJOw"},"name":{"type":"string","description":"Channel name","example":"Rick Astley"},"thumbnail":{"type":"string","description":"Channel thumbnail URL","example":"https://yt3.ggpht.com/..."}},"required":["id","name"],"description":"Channel information (for videos and playlists)"},"subscriberCount":{"type":"number","description":"Subscriber count (for channels only)","example":2000000},"videoCount":{"type":"number","description":"Video count (for channels and playlists only)","example":100}},"required":["type","id","title"],"description":"Search result item"},"description":"Array of search results"},"totalResults":{"type":"number","description":"Estimated total number of results","example":1000000},"nextPageToken":{"type":"string","description":"Token for fetching the next page of results. Only returned when limit parameter is not provided.","example":"eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319"}},"required":["query","results"]},"Scrape":{"type":"object","properties":{"url":{"type":"string","description":"The URL that was scraped","example":"https://supadata.ai"},"content":{"type":"string","description":"The Markdown content extracted from the URL","example":"# Supadata\n## What is Supadata?\nSupadata is an API platform for data extraction for LLM training."},"name":{"type":"string","description":"The name of the webpage","example":"Supadata: Web & YouTube to text API for developers"},"description":{"type":"string","description":"A description of the webpage","example":"Supadata is one stop-shop API for developers to read web and YouTube content, ready for AI training and retrieval."},"ogUrl":{"type":"string","description":"Open Graph URL for the webpage","example":"https://supadata.ai/opengraph-image.png"},"countCharacters":{"type":"number","description":"The number of characters in the content","example":12300},"urls":{"type":"array","items":{"type":"string"},"description":"List of URLs found on the webpage","example":["https://supadata.ai","https://docs.supadata.ai"]}},"required":["url","content","countCharacters","urls"]},"UrlQuery":{"type":"string","description":"URL of the webpage","example":"https://supadata.ai"},"Map":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string"},"description":"List of URLs found on the webpage","example":["https://supadata.ai","https://docs.supadata.ai"]}},"required":["urls"]},"CrawlJob":{"type":"object","properties":{"status":{"type":"string","enum":["scraping","completed","failed","cancelled"],"description":"The status of the crawl job","example":"completed"},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"The URL that was scraped","example":"https://supadata.ai"},"content":{"type":"string","description":"The Markdown content extracted from the URL","example":"# Supadata\n## What is Supadata?\nSupadata is an API platform for data extraction for LLM training."},"name":{"type":"string","description":"The name of the webpage","example":"Supadata: Web & YouTube to text API for developers"},"description":{"type":"string","description":"A description of the webpage","example":"Supadata is one stop-shop API for developers to read web and YouTube content, ready for AI training and retrieval."},"ogUrl":{"type":"string","description":"Open Graph URL for the webpage","example":"https://supadata.ai/opengraph-image.png"},"countCharacters":{"type":"number","description":"The number of characters in the content","example":12300}},"required":["url","content","countCharacters"]},"description":"List of pages that were crawled (only present when status is completed)"},"next":{"type":"string","description":"URL for fetching the next page of results","example":"https://api.supadata.ai/v1/crawl/123e4567-e89b-12d3-a456-426614174000?skip=1"}},"required":["status"]},"TranscriptOrJobId":{"anyOf":[{"$ref":"#/components/schemas/Transcript"},{"$ref":"#/components/schemas/JobId"}],"description":"Either a transcript result (synchronous) or a job ID (asynchronous)."},"JobResult":{"type":"object","properties":{"status":{"type":"string","enum":["queued","active","completed","failed"],"description":"Current status of the job","example":"completed"},"error":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"type":"null"}],"description":"Error information if the job failed"},"content":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/TranscriptChunk"}},{"type":"string","description":"Plain text transcript when text=true parameter is used","example":"Never gonna give you up, never gonna let you down..."}]},"lang":{"type":"string","description":"ISO 639-1 language code of transcript","example":"en"},"availableLangs":{"type":"array","items":{"type":"string"},"description":"List of available language codes","example":["en","es","zh-TW"]}},"required":["status"],"description":"Response for job status/results"},"Metadata":{"type":"object","properties":{"platform":{"type":"string","enum":["youtube","tiktok","instagram","twitter","facebook"],"description":"Platform where the media is hosted"},"type":{"allOf":[{"$ref":"#/components/schemas/MediaType"}],"example":"video"},"id":{"type":"string","description":"Unique media identifier from the platform","example":"dQw4w9WgXcQ"},"url":{"type":"string","description":"Canonical URL to the media","example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},"title":{"type":["string","null"],"description":"Media title","example":"Amazing Video Title"},"description":{"type":["string","null"],"description":"Media description or caption","example":"Check out this amazing content! #awesome"},"author":{"type":"object","properties":{"username":{"type":"string","example":"username"},"displayName":{"type":"string","example":"John Doe"},"avatarUrl":{"type":"string","example":"https://example.com/avatar.jpg"},"verified":{"type":"boolean","example":true,"description":"Whether the author is verified on the platform"}},"required":["displayName"],"description":"Author/creator information"},"stats":{"type":"object","properties":{"views":{"type":["number","null"],"example":50000,"description":"View count. null if unavailable or not applicable for the platform."},"likes":{"type":["number","null"],"example":5000,"description":"Like count. null if unavailable or not applicable for the platform."},"comments":{"type":["number","null"],"example":200,"description":"Comment count. null if unavailable or not applicable for the platform."},"shares":{"type":["number","null"],"example":100,"description":"Share count. null if unavailable or not applicable for the platform (e.g., YouTube, Instagram)."}},"required":["likes","comments","shares"],"description":"Engagement statistics. null values indicate the metric is unavailable or not applicable for the platform."},"media":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"video","description":"Media type discriminator"},"duration":{"type":"number","example":30,"description":"Video duration in seconds"},"thumbnailUrl":{"type":"string","example":"https://example.com/thumb.jpg","description":"Largest/best quality thumbnail URL"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"image","description":"Media type discriminator"},"url":{"type":"string","example":"https://example.com/image.jpg","description":"Direct URL to the image"}},"required":["type","url"]},{"type":"object","properties":{"type":{"type":"string","const":"carousel","description":"Media type discriminator"},"items":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"video","description":"Video item"},"duration":{"type":"number","description":"Video duration in seconds"},"thumbnailUrl":{"type":"string","description":"Video thumbnail URL"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"image","description":"Image item"},"url":{"type":"string","description":"Direct URL to the image"}},"required":["type","url"]}]},"description":"Array of carousel items (images or videos)"}},"required":["type","items"]},{"type":"object","properties":{"type":{"type":"string","const":"post","description":"Media type discriminator for text-only posts"}},"required":["type"]}],"description":"Media-specific data, discriminated by type field (video, image, carousel, or post)"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags, hashtags, or keywords associated with the media","example":["funny","cats","viral"]},"createdAt":{"type":"string","description":"Creation/publish timestamp (ISO 8601 format)","example":"2024-01-15T10:30:00Z"},"additionalData":{"type":"object","additionalProperties":{},"description":"Platform-specific additional data"}},"required":["platform","type","id"]},"MediaType":{"type":"string","enum":["video","image","carousel","post"],"description":"Type of media content"},"MetadataQuery":{"type":"string","format":"uri","description":"URL to any supported internet media. Supports YouTube videos, TikTok videos, Instagram reels/posts, Twitter/X posts, Facebook videos, and more.","examples":["https://www.youtube.com/watch?v=dQw4w9WgXcQ","https://www.tiktok.com/@user/video/1234567890","https://www.instagram.com/reel/ABC123","https://twitter.com/user/status/1234567890","https://www.facebook.com/i/videos/1234567890"]},"ExtractRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL to any supported video media. Supports YouTube, TikTok, Instagram, Twitter/X, and Facebook videos.","examples":["https://www.youtube.com/watch?v=dQw4w9WgXcQ","https://www.tiktok.com/@user/video/1234567890","https://www.instagram.com/reel/ABC123"]},"prompt":{"type":"string","description":"Natural language description of what data to extract from the video. Required if schema is not provided. Do not include JSON structure definitions here — use the \"schema\" field instead.","example":"Extract the main topics discussed and key takeaways"},"schema":{"type":"object","additionalProperties":{},"description":"JSON Schema defining the structure of data to extract. Required if prompt is not provided.","example":{"type":"object","properties":{"topics":{"type":"array","items":{"type":"string"},"description":"Main topics discussed"},"summary":{"type":"string","description":"Brief summary of the video"}},"required":["topics","summary"]}}},"required":["url"]},"ExtractJobResult":{"type":"object","properties":{"status":{"type":"string","enum":["queued","active","completed","failed"],"description":"Current status of the job","example":"completed"},"error":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"type":"null"}],"description":"Error information if the job failed"},"data":{"type":"object","additionalProperties":{},"description":"Extracted data from the video, structured according to the schema","example":{"topics":["AI basics","Machine learning","Neural networks"],"summary":"An introduction to artificial intelligence concepts"}},"schema":{"type":"object","additionalProperties":{},"description":"JSON Schema generated by AI. Only present when no schema was provided in the request.","example":{"type":"object","properties":{"topics":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"}},"required":["topics","summary"]}}},"required":["status"],"description":"Response for extract job status/results"},"Me":{"type":"object","properties":{"organizationId":{"type":"string","description":"Unique identifier for the organization","example":"550e8400-e29b-41d4-a716-446655440000"},"plan":{"type":"string","description":"Subscription plan name","example":"Pro"},"maxCredits":{"type":"number","description":"Maximum credits available for the current billing period","example":100000},"usedCredits":{"type":"number","description":"Number of credits used in the current billing period","example":15000}},"required":["organizationId","plan","maxCredits","usedCredits"]}}},"security":[{"apiKeyAuth":[]}],"paths":{"/youtube/video":{"get":{"responses":{"200":{"description":"Successfully fetched video metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeVideo"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getYoutubeVideo","parameters":[{"in":"query","name":"id","schema":{"type":"string","description":"YouTube video URL or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","examples":["https://youtu.be/dQw4w9WgXcQ","dQw4w9WgXcQ"]},"required":true}],"description":"Get metadata for a YouTube video.","deprecated":true,"x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst video = await supadata.youtube.video({\n  id: 'https://youtu.be/dQw4w9WgXcQ', // can be id or url\n});\nconsole.log(video.title);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\nvideo = supadata.youtube.video(\n    id=\"https://youtu.be/dQw4w9WgXcQ\" # can be id or url\n)\nprint(f\"Video title: {video.title}\")\nprint(f\"Channel: {video.channel.name}\")"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/youtube/video?id=https://youtu.be/dQw4w9WgXcQ\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/youtube/playlist":{"get":{"responses":{"200":{"description":"Successfully fetched playlist metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubePlaylist"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getYoutubePlaylist","parameters":[{"in":"query","name":"id","schema":{"type":"string","description":"YouTube playlist URL or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","examples":["https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc","PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc"]},"required":true}],"description":"Get metadata for a YouTube playlist.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst playlist = await supadata.youtube.playlist({\n  id: 'https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc', // can be id or url\n});\nconsole.log(`Playlist ${playlist.title} contains ${playlist.videoCount} videos`);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\nplaylist = supadata.youtube.playlist(\n    id=\"https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc\" # can be id or url\n)\nprint(f\"Playlist title: {playlist.title} contains {playlist.video_count} videos\")"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/youtube/playlist?id=https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/youtube/playlist/videos":{"get":{"responses":{"200":{"description":"Successfully fetched playlist video IDs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoIds"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getYoutubePlaylistVideos","parameters":[{"in":"query","name":"id","schema":{"type":"string","description":"YouTube playlist URL or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","examples":["https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc","PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc"]},"required":true},{"in":"query","name":"limit","schema":{"type":"number","minimum":1,"maximum":5000,"default":100,"description":"Maximum number of video IDs to return","example":10},"required":false}],"description":"Get video IDs from a YouTube playlist.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst videos = await supadata.youtube.playlist.videos({\n  id: 'https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc', // can be id or url\n  limit: 20, // Optional: limit the number of videos to fetch\n});\nconsole.log(`Found ${videos.videoIds.length} videos`);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\nvideos = supadata.youtube.playlist.videos(\n    id=\"https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc\", # can be id or url\n    limit=20  # Optional: limit the number of videos to fetch\n)\nprint(f\"Found {len(videos.video_ids)} videos\")\nprint(videos.video_ids)"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/youtube/playlist/videos?id=https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc&limit=20\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/youtube/channel":{"get":{"responses":{"200":{"description":"Successfully fetched channel metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeChannel"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getYoutubeChannel","parameters":[{"in":"query","name":"id","schema":{"type":"string","description":"YouTube channel URL, handle or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","examples":["https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw","https://youtube.com/c/rickastley","UCuAXFkgsw1L7xaCfnd5JJOw","@rickastley","rickastley"]},"required":true}],"description":"Get metadata for a YouTube channel.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst channel = await supadata.youtube.channel({\n  id: 'RickAstleyVEVO', // can be url, id, handle\n});\nconsole.log(channel.name);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\nchannel = supadata.youtube.channel(\n    id=\"RickAstleyVEVO\" # can be url, id, handle\n)\nprint(f\"Channel name: {channel.name}\")"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/youtube/channel?id=RickAstleyVEVO\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/youtube/channel/videos":{"get":{"responses":{"200":{"description":"Successfully fetched channel video IDs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoIds"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getYoutubeChannelVideos","parameters":[{"in":"query","name":"id","schema":{"type":"string","description":"YouTube channel URL, handle or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","examples":["https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw","https://youtube.com/c/rickastley","UCuAXFkgsw1L7xaCfnd5JJOw","@rickastley","rickastley"]},"required":true},{"in":"query","name":"limit","schema":{"type":"number","minimum":1,"maximum":5000,"default":30,"description":"Maximum number of video IDs to return. If type = all, vertical videos are prioritized.","example":10},"required":false},{"in":"query","name":"type","schema":{"type":"string","enum":["all","video","short","live"],"description":"Type of videos to return.","example":"video","default":"all"},"required":false}],"description":"Get video IDs from a YouTube channel.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst videos = await supadata.youtube.channel.videos({\n  id: 'RickAstleyVEVO', // can be url, id, handle\n  limit: 50, // Optional: limit the number of videos to fetch\n  type: 'all', // Optional: 'all', 'video', 'short', 'live' (default 'all')\n});\nconsole.log(`Found ${videos.videoIds.length} regular videos, ${videos.shortIds.length} shorts, and ${videos.liveIds.length} live streams.`);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\nvideos = supadata.youtube.channel.videos(\n    id=\"RickAstleyVEVO\", # can be url, id, handle\n    limit=50,  # Optional: limit the number of videos to fetch\n    type=\"all\" # Optional: 'all', 'video', 'short', 'live'  (default 'all')\n)\nprint(f\"Found {len(videos.video_ids)} regular videos, {len(videos.short_ids)} shorts, and {len(videos.live_ids)} live streams.\")"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/youtube/channel/videos?id=RickAstleyVEVO&limit=50&type=all\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/youtube/transcript":{"get":{"responses":{"200":{"description":"Successfully fetched transcript","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"}}}},"206":{"description":"Transcript Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getYoutubeTranscript","parameters":[{"in":"query","name":"url","schema":{"type":"string","format":"uri","description":"YouTube video URL. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","example":"https://youtu.be/dQw4w9WgXcQ"}},{"in":"query","name":"videoId","schema":{"type":"string","description":"YouTube video ID. Alternative to URL.","example":"dQw4w9WgXcQ"}},{"in":"query","name":"text","schema":{"type":"boolean","description":"When true, returns plain text transcript.","default":false}},{"in":"query","name":"chunkSize","schema":{"type":"number","minimum":50,"maximum":10000,"description":"Maximum characters per transcript chunk (only when text=false)","example":1000}},{"in":"query","name":"lang","schema":{"type":"string","description":"Preferred language code of the transcript (ISO 639-1). If not provided, the first available language will be returned. If the requested language is unavailable, the API defaults to the first available language. See [Languages](https://docs.supadata.ai/youtube/supported-language-codes).","example":"en"}}],"description":"Get transcript from YouTube video in various formats and languages. If the `lang` parameter is not provided or the transcript is not available in the requested language, the API defaults to the first available language.","deprecated":true,"x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst transcript = await supadata.youtube.transcript({\n  url: 'https://youtu.be/dQw4w9WgXcQ',\n  lang: 'en',\n  text: true,\n});\nconsole.log(transcript);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\ntext_transcript = supadata.youtube.transcript(\n    url=\"https://youtu.be/dQw4w9WgXcQ\",\n    lang=\"en\",\n    text=True # Set to False to get the transcript with timestamps\n)\nprint(text_transcript.content)"},{"lang":"Shell","label":"cURL - Using URL","source":"curl -X GET \"https://api.supadata.ai/v1/youtube/transcript?url=https://youtu.be/dQw4w9WgXcQ&lang=en\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/youtube/transcript/translate":{"get":{"responses":{"200":{"description":"Successfully translated transcript","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslatedTranscript"}}}},"206":{"description":"Transcript Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getYoutubeTranscriptTranslate","parameters":[{"in":"query","name":"url","schema":{"type":"string","format":"uri","description":"YouTube video URL. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","example":"https://youtu.be/dQw4w9WgXcQ"},"required":false},{"in":"query","name":"videoId","schema":{"type":"string","description":"YouTube video ID. Alternative to URL.","example":"dQw4w9WgXcQ"},"required":false},{"in":"query","name":"text","schema":{"type":"boolean","description":"When true, returns plain text transcript.","default":false},"required":false},{"in":"query","name":"chunkSize","schema":{"type":"number","minimum":50,"maximum":10000,"description":"Maximum characters per transcript chunk (only when text=false)","example":1000},"required":false},{"in":"query","name":"lang","schema":{"type":"string","description":"Language code for translation (ISO 639-1). See [Languages](https://docs.supadata.ai/youtube/supported-language-codes).","example":"en"},"required":true}],"description":"Translate YouTube video transcript into different languages.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst translated = await supadata.youtube.translate({\n  url: 'https://youtu.be/dQw4w9WgXcQ',\n  lang: 'es',\n  text: false,\n});\nconsole.log(translated);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\ntranslated = supadata.youtube.translate(\n    url=\"https://youtu.be/dQw4w9WgXcQ\",\n    lang=\"es\",\n    text=False\n)\nprint(f\"Got translated transcript in {translated.lang}\")"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/youtube/transcript/translate?url=https://youtu.be/dQw4w9WgXcQ&lang=es\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/youtube/transcript/batch":{"post":{"responses":{"200":{"description":"Successfully created a batch job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobId"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postYoutubeTranscriptBatch","parameters":[],"description":"Create a batch job to get transcripts of multiple YouTube videos","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"videoIds":{"type":"array","items":{"type":"string"},"description":"Array of YouTube video IDs or URLs","example":["dQw4w9WgXcQ","https://www.youtube.com/watch?v=xvFZjo5PgG0"]},"playlistId":{"type":"string","description":"YouTube playlist URL or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","examples":["https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc","PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc"]},"channelId":{"type":"string","description":"YouTube channel URL, handle or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","examples":["https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw","https://youtube.com/c/rickastley","UCuAXFkgsw1L7xaCfnd5JJOw","@rickastley","rickastley"]},"limit":{"type":"number","minimum":1,"maximum":5000,"description":"Maximum number of videos to process (when using playlistId or channelId)","example":20,"default":10},"lang":{"type":"string","description":"Preferred language code of the transcript (ISO 639-1). If not provided, the first available language will be returned. If the requested language is unavailable, the API defaults to the first available language. See [Languages](https://docs.supadata.ai/youtube/supported-language-codes).","example":"en"},"text":{"type":"boolean","description":"When true, returns plain text transcript.","default":false}},"oneOf":[{"required":["videoIds"]},{"required":["playlistId"]},{"required":["channelId"]}]}}}},"x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\n\nconst transcriptBatch = await supadata.youtube.transcript.batch({\n  videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'],\n  // playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' // alternatively\n  // channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively\n  lang: 'en',\n  text: true\n});\nconsole.log(`Started transcript batch job: ${transcriptBatch.jobId}`);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata, SupadataError\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\n\ntranscript_batch = supadata.youtube.transcript.batch(\n    video_ids=[\"dQw4w9WgXcQ\", \"xvFZjo5PgG0\"],\n    # playlist_id=\"PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc\" # alternatively\n    # channel_id=\"UC_9-kyTW8ZkZNDHQJ6FgpwQ\" # alternatively\n    lang=\"en\",\n    text=True\n)\nprint(f\"Started transcript batch job: {transcript_batch.job_id}\")"},{"lang":"Shell","label":"cURL","source":"curl -X POST \"https://api.supadata.ai/v1/youtube/transcript/batch\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"videoIds\": [\"dQw4w9WgXcQ\", \"xvFZjo5PgG0\"],\n    \"lang\": \"en\",\n    \"text\": true\n  }'"}]}},"/youtube/video/batch":{"post":{"responses":{"200":{"description":"Successfully created a batch job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobId"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postYoutubeVideoBatch","parameters":[],"description":"Create a batch job to fetch metadata of multiple YouTube videos","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"videoIds":{"type":"array","items":{"type":"string"},"description":"Array of YouTube video IDs or URLs","example":["dQw4w9WgXcQ","https://www.youtube.com/watch?v=xvFZjo5PgG0"]},"playlistId":{"type":"string","description":"YouTube playlist URL or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","examples":["https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc","PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc"]},"channelId":{"type":"string","description":"YouTube channel URL, handle or ID. See [supported URL formats](https://docs.supadata.ai/youtube/supported-url-formats).","examples":["https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw","https://youtube.com/c/rickastley","UCuAXFkgsw1L7xaCfnd5JJOw","@rickastley","rickastley"]},"limit":{"type":"number","minimum":1,"maximum":5000,"description":"Maximum number of videos to process (when using playlistId or channelId)","example":20,"default":10}},"oneOf":[{"required":["videoIds"]},{"required":["playlistId"]},{"required":["channelId"]}]}}}},"x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\n\nconst batchJob = await supadata.youtube.video.batch({\n  videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0', 'L_jWHffIx5E']\n  // playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' // alternatively\n  // channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively\n});\nconsole.log(`Started batch job: ${batchJob.jobId}`);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata, SupadataError\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\n\nbatch_job = supadata.youtube.video.batch(\n    video_ids=[\"dQw4w9WgXcQ\", \"xvFZjo5PgG0\", \"L_jWHffIx5E\"]\n    # playlist_id=\"PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc\" # alternatively\n    # channel_id=\"UC_9-kyTW8ZkZNDHQJ6FgpwQ\" # alternatively\n)\nprint(f\"Started batch job: {batch_job.job_id}\")"},{"lang":"Shell","label":"cURL","source":"curl -X POST \"https://api.supadata.ai/v1/youtube/video/batch\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"videoIds\": [\"dQw4w9WgXcQ\", \"xvFZjo5PgG0\"]\n  }'"}]}},"/youtube/batch/{jobId}":{"get":{"responses":{"200":{"description":"Successfully retrieved the status and results (if completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YouTubeBatchResults"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getYoutubeBatchByJobId","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"},"description":"The batch job ID"}],"description":"Get the status and results of a YouTube batch job.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\n\nconst batchResults = await supadata.youtube.batch.getBatchResults(JOB_ID);\nconsole.log(batchResults);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata, SupadataError\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\n\nbatch_results = supadata.youtube.batch.get_batch_results(job_id=JOB_ID)\nprint(batch_results)"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/youtube/batch/JOB_ID\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/youtube/search":{"get":{"responses":{"200":{"description":"Successfully retrieved search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeSearch"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getYoutubeSearch","parameters":[{"in":"query","name":"query","schema":{"type":"string","minLength":1,"description":"Search query string","example":"Never Gonna Give You Up"},"required":true},{"in":"query","name":"uploadDate","schema":{"type":"string","enum":["all","hour","today","week","month","year"],"description":"Filter by upload date (eg. last month). Note: works only for videos and movies.","example":"month","default":"all"},"required":false},{"in":"query","name":"type","schema":{"type":"string","enum":["all","video","channel","playlist","movie"],"description":"Filter by content type","example":"video","default":"all"},"required":false},{"in":"query","name":"duration","schema":{"type":"string","enum":["all","short","medium","long"],"description":"Filter by video duration: short (<4min), medium (4-20min), long (>20min). Note: works only for videos and movies.","example":"medium","default":"all"},"required":false},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["relevance","rating","date","views"],"description":"Sort order of search results.","example":"views","default":"relevance"},"required":false},{"in":"query","name":"features","schema":{"type":"array","items":{"type":"string","enum":["hd","subtitles","creative-commons","3d","live","4k","360","location","hdr","vr180"]},"description":"Array of special features to filter by. Note: works only for videos and movies.","example":["hd","subtitles","creative-commons"]},"required":false},{"in":"query","name":"limit","schema":{"type":"number","minimum":1,"maximum":5000,"description":"Maximum number of results to return. When provided, the API will automatically paginate to fetch up to this many results. When omitted, returns a single page with `nextPageToken` for manual pagination.","example":50},"required":false},{"in":"query","name":"nextPageToken","schema":{"type":"string","description":"Token for fetching the next page of results. When provided, other filter parameters are ignored.","example":"eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319"},"required":false}],"description":"Search YouTube for videos, channels, and playlists with advanced filters.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst searchResults = await supadata.youtube.search({\n  query: 'rick astley never gonna give you up',\n  type: 'video', // Optional: 'video', 'channel', 'playlist', 'all' (default 'all')\n  limit: 20, // Optional: get more than the first page of results\n  sortBy: 'views', // Optional: 'relevance', 'rating', 'date', 'views'\n  uploadDate: 'year', // Optional: 'hour', 'today', 'week', 'month', 'year'\n  duration: 'medium', // Optional: 'short', 'medium', 'long'\n});\nconsole.log(`Found ${searchResults.results.length} results`);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\nsearch_results = supadata.youtube.search(\n    query=\"rick astley never gonna give you up\",\n    type=\"video\",  # Optional: 'video', 'channel', 'playlist', 'all' (default 'all')\n    limit=20,  # Optional: get more than the first page of results\n    sort_by=\"views\",  # Optional: 'relevance', 'rating', 'date', 'views'\n    upload_date=\"year\",  # Optional: 'hour', 'today', 'week', 'month', 'year'\n    duration=\"medium\"  # Optional: 'short', 'medium', 'long'\n)\nprint(f\"Found {len(search_results.results)} results\")\nfor result in search_results.results:\n    print(f\"{result.type}: {result.title}\")"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/youtube/search?query=rick%20astley%20never%20gonna%20give%20you%20up&type=video&limit=20&sortBy=views&uploadDate=month\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/web/scrape":{"get":{"responses":{"200":{"description":"Successfully fetched web page content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scrape"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getWebScrape","parameters":[{"in":"query","name":"url","schema":{"$ref":"#/components/schemas/UrlQuery"},"required":true},{"in":"query","name":"noLinks","schema":{"type":"boolean","description":"When true, removes markdown links from the content, leaving only the URL text.","default":false},"required":false},{"in":"query","name":"lang","schema":{"type":"string","description":"Preferred language for the scraped content (ISO 639-1 code). Sets Accept-Language header to influence website language selection.","example":"en","default":"en"},"required":false}],"description":"Extract content from any web page to Markdown format.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst webContent = await supadata.web.scrape('https://example.com');\nconsole.log(webContent);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\nweb_content = supadata.web.scrape(\"https://example.com\")\nprint(f\"Page content: {web_content.content}\")"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/web/scrape?url=https://example.com\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/web/map":{"get":{"responses":{"200":{"description":"Successfully mapped web page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Map"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getWebMap","parameters":[{"in":"query","name":"url","schema":{"$ref":"#/components/schemas/UrlQuery"},"required":true},{"in":"query","name":"noLinks","schema":{"type":"boolean","description":"When true, removes markdown links from the content, leaving only the URL text.","default":false},"required":false},{"in":"query","name":"lang","schema":{"type":"string","description":"Preferred language for the scraped content (ISO 639-1 code). Sets Accept-Language header to influence website language selection.","example":"en","default":"en"},"required":false}],"description":"Extract all links found on a whole website.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\nconst siteMap = await supadata.web.map('https://example.com');\nconsole.log(siteMap);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\nsite_map = supadata.web.map(\"https://example.com\")\nprint(f\"Found {len(site_map.urls)} URLs\")"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/web/map?url=https://example.com\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/web/crawl":{"post":{"responses":{"200":{"description":"Successfully started crawl job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobId"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postWebCrawl","parameters":[],"description":"Create a crawl job to extract content from all pages on a website.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\n\n// Start a crawl job\nconst crawl = await supadata.web.crawl({\n  url: 'https://example.com',\n  limit: 10,\n});\n\n// Get crawl job results\n// This automatically handles pagination and returns all pages\nconst crawlResults = await supadata.web.getCrawlResults(crawl.jobId);\nconsole.log(crawlResults);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata, SupadataError\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\n\n# Start a crawl job\ncrawl_job = supadata.web.crawl(\n    url=\"https://example.com\",\n    limit=10  # Optional: limit the number of pages to crawl\n)\nprint(f\"Started crawl job: {crawl_job.job_id}\")\n\n# Get crawl results\n# This automatically handles pagination and returns all pages\ntry:\n    pages = supadata.web.get_crawl_results(job_id=crawl_job.job_id)\n    for page in pages:\n        print(f\"Crawled page: {page.url}\")\n        print(f\"Page title: {page.name}\")\n        print(f\"Content: {page.content}\")\nexcept SupadataError as e:\n    print(f\"Crawl job failed: {e}\")"},{"lang":"Shell","label":"cURL - Start Crawl","source":"curl -X POST \"https://api.supadata.ai/v1/web/crawl\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://example.com\",\n    \"limit\": 10\n  }'"},{"lang":"Shell","label":"cURL - Get Crawl Results","source":"curl -X GET \"https://api.supadata.ai/v1/web/crawl/JOB_ID\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL of the website to crawl","example":"https://supadata.ai"},"limit":{"type":"number","minimum":1,"maximum":5000,"description":"Maximum number of pages to crawl","example":100,"default":100}},"required":["url"]}}}}}},"/web/crawl/{jobId}":{"get":{"responses":{"200":{"description":"Successfully retrieved crawl status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrawlJob"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getWebCrawlByJobId","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"},"description":"The crawl job ID"},{"in":"query","name":"skip","schema":{"type":"number","minimum":0}}],"description":"Get the status and results of a crawl by job ID.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\n\n// Start a crawl job\nconst crawl = await supadata.web.crawl({\n  url: 'https://example.com',\n  limit: 10,\n});\n\n// Get crawl job results\n// This automatically handles pagination and returns all pages\nconst crawlResults = await supadata.web.getCrawlResults(crawl.jobId);\nconsole.log(crawlResults);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata, SupadataError\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\n\n# Start a crawl job\ncrawl_job = supadata.web.crawl(\n    url=\"https://example.com\",\n    limit=10  # Optional: limit the number of pages to crawl\n)\nprint(f\"Started crawl job: {crawl_job.job_id}\")\n\n# Get crawl results\n# This automatically handles pagination and returns all pages\ntry:\n    pages = supadata.web.get_crawl_results(job_id=crawl_job.job_id)\n    for page in pages:\n        print(f\"Crawled page: {page.url}\")\n        print(f\"Page title: {page.name}\")\n        print(f\"Content: {page.content}\")\nexcept SupadataError as e:\n    print(f\"Crawl job failed: {e}\")"},{"lang":"Shell","label":"cURL - Start Crawl","source":"curl -X POST \"https://api.supadata.ai/v1/web/crawl\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://example.com\",\n    \"limit\": 10\n  }'"},{"lang":"Shell","label":"cURL - Get Crawl Results","source":"curl -X GET \"https://api.supadata.ai/v1/web/crawl/JOB_ID\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/transcript":{"get":{"responses":{"200":{"description":"Successfully fetched or generated transcript","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptOrJobId"}}}},"202":{"description":"Job ID for asynchronous processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptOrJobId"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getTranscript","parameters":[{"in":"query","name":"url","schema":{"type":"string","format":"uri","description":"Video URL from any supported platform (YouTube, TikTok, Twitter, Instagram) or a file URL.","example":"https://youtu.be/dQw4w9WgXcQ"},"required":true},{"in":"query","name":"lang","schema":{"type":"string","description":"Preferred language code of the transcript (ISO 639-1). If not provided, the first available language will be returned. If the requested language is unavailable, the API defaults to the first available language. See [Languages](https://docs.supadata.ai/youtube/supported-language-codes).","example":"en"},"required":false},{"in":"query","name":"text","schema":{"type":"boolean","description":"When true, returns plain text transcript.","default":false},"required":false},{"in":"query","name":"chunkSize","schema":{"type":"number","minimum":50,"maximum":10000,"description":"Maximum characters per transcript chunk (only when text=false)","example":1000},"required":false},{"in":"query","name":"mode","schema":{"type":"string","enum":["native","auto","generate"],"default":"auto","description":"Transcript mode: `native` (only fetch existing transcript), `generate` (always generate transcript using AI), or `auto` (try native, fallback to generate if unavailable). If url is a file URL, mode is always `generate`.","example":"auto"},"required":false}],"description":"Get transcript from a supported video platform (YouTube, TikTok, Twitter, Instagram, Facebook) or file URL. If the video is too large to return transcript immediately, request returns a job ID. Use the `/transcript/:jobId` endpoint to get job results.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\n\n// Get transcript or job ID\nconst transcriptResult = await supadata.transcript({\n  url: 'https://youtu.be/dQw4w9WgXcQ',\n  lang: 'en',\n  text: true,\n  mode: 'auto' // 'native', 'auto', or 'generate'\n});\nconsole.log(transcript);\n\nif ('jobId' in transcriptJob) {\n  // Check job result\n  const result = await supadata.transcript.getJobStatus(transcriptJob.jobId);\n  console.log(result);\n}"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\n\n# Get transcript or job ID\ntranscript_result = supadata.transcript(\n    url=\"https://youtu.be/dQw4w9WgXcQ\",\n    lang=\"en\",\n    text=True,\n    mode=\"auto\"  # 'native', 'auto', or 'generate'\n)\nprint(f\"Got transcript result or job ID: {transcript_result}\")\n\nif hasattr(transcript_result, 'job_id'):\n    # Check job result\n    result = supadata.transcript.get_job_status(transcript_result.job_id)\n    print(f\"Job status: {result.status}\")\n    if result.status == \"completed\":\n        print(result.content)"},{"lang":"Shell","label":"cURL - Get Transcript","source":"curl -X GET \"https://api.supadata.ai/v1/transcript?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ&lang=en&text=true&mode=auto\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""},{"lang":"Shell","label":"cURL - Get Job Status","source":"curl -X GET \"https://api.supadata.ai/v1/transcript/JOB_ID\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/transcript/{jobId}":{"get":{"responses":{"200":{"description":"Transcript job result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResult"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getTranscriptByJobId","parameters":[{"schema":{"type":"string"},"in":"path","name":"jobId","required":true}],"description":"Get results for a transcript job by job ID.","x-codeSamples":[{"lang":"Shell","label":"cURL - Get Job Status","source":"curl -X GET \"https://api.supadata.ai/v1/transcript/JOB_ID\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/metadata":{"get":{"responses":{"200":{"description":"Metadata retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getMetadata","tags":["Metadata"],"parameters":[{"in":"query","name":"url","schema":{"$ref":"#/components/schemas/MetadataQuery"},"required":true}],"summary":"Get media metadata","description":"Fetch metadata from any supported internet media including YouTube, TikTok, Instagram, Twitter/X and Facebook posts. Returns unified metadata with a predictable structure across all platforms.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({\n  apiKey: 'YOUR_API_KEY',\n});\n\n// TikTok video, can be also YouTube, Instagram, Twitter, Facebook\nconst tiktokMetadata = await supadata.metadata({\n  url: 'https://www.tiktok.com/@user/video/1234567890',\n});\nconsole.log(tiktokMetadata);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\n\n# TikTok video, can be also YouTube, Instagram, Twitter, Facebook\ntiktok_metadata = supadata.metadata(\n    url=\"https://www.tiktok.com/@user/video/1234567890\"\n)\nprint(f\"Caption: {tiktok_metadata.description}\")\nprint(f\"Likes: {tiktok_metadata.stats.likes}\")"},{"lang":"Shell","label":"cURL","source":"curl -X GET \"https://api.supadata.ai/v1/metadata?url=https%3A%2F%2Fwww.tiktok.com%2F%40user%2Fvideo%2F1234567890\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}]}},"/extract":{"post":{"responses":{"202":{"description":"Job created for asynchronous processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobId"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"postExtract","tags":["Extract"],"parameters":[],"summary":"Extract structured data from video","description":"Use AI to analyze video content and extract structured data. Provide either a prompt describing what to extract, a JSON Schema for the output format, or both. Supports YouTube, TikTok, Instagram, Twitter/X, and Facebook videos. Returns a job ID for asynchronous processing. Use the `/extract/:jobId` endpoint to poll for results.","x-codeSamples":[{"lang":"TypeScript","label":"Node.js","source":"import { Supadata } from '@supadata/js';\n\nconst supadata = new Supadata({ apiKey: 'YOUR_API_KEY' });\n\n// Start extract job\nconst job = await supadata.extract({\n  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',\n  prompt: 'Extract the main topics and key takeaways',\n});\n\n// Get job results\nconst result = await supadata.extract.getResults(job.jobId);\nconsole.log(result.data);"},{"lang":"Python","label":"Python","source":"from supadata import Supadata\n\nsupadata = Supadata(api_key=\"YOUR_API_KEY\")\n\n# Start extract job\njob = supadata.extract(\n    url=\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\",\n    prompt=\"Extract the main topics and key takeaways\"\n)\n\n# Get job results\nresult = supadata.extract.get_results(job.job_id)\nprint(result.data)"},{"lang":"Shell","label":"cURL - Start Extract Job","source":"curl -X POST \"https://api.supadata.ai/v1/extract\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\",\n    \"prompt\": \"Extract the main topics and key takeaways\"\n  }'"},{"lang":"Shell","label":"cURL - Get Extract Results","source":"curl -X GET \"https://api.supadata.ai/v1/extract/JOB_ID\" \\\n  -H \"x-api-key: YOUR_API_KEY\""}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractRequest"}}}}}},"/extract/{jobId}":{"get":{"responses":{"200":{"description":"Extract job result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractJobResult"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getExtractByJobId","tags":["Extract"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"jobId","required":true}],"summary":"Get extract job status","description":"Get results for an extract job by job ID."}},"/me":{"get":{"responses":{"200":{"description":"Account information retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getMe","tags":["Account"],"parameters":[],"summary":"Get account information","description":"Retrieve organization details, plan information, and credit usage."}}}}