{ "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 (empty string when the playlist has none)", "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" }, "handle": { "type": "string", "description": "Channel handle (empty string when the channel has none)", "example": "@RickAstleyYT" }, "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" }, "errorCode": { "type": "string", "enum": [ "job-expired" ], "description": "Set to `job-expired` when the batch aged out before finishing; its results are no longer available.", "example": "job-expired" }, "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", "processing", "result-unavailable" ], "description": "Error code if processing this item failed. `processing` means the item has not finished yet; `result-unavailable` means the batch completed but this item's result is no longer available.", "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)" }, "handle": { "type": "string", "description": "Channel handle (for channels only)", "example": "@RickAstleyYT" }, "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" }, "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 (the same endpoint with a `skip` offset). Only present when more pages are available.", "example": "https://api.supadata.ai/v1/web/crawl/123e4567-e89b-12d3-a456-426614174000?skip=10" } }, "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, or a direct media file URL.", "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, regular (landscape) videos are filled first, then Shorts, then live streams.", "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. Batches created from a playlist or channel include regular videos only (Shorts and live streams are skipped).", "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. Batches created from a playlist or channel include regular videos only (Shorts and live streams are skipped).", "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" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Return at most this many results (with `offset`, pages through a completed batch). Omit both to receive all results in one streamed response." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Skip this many results (in submission order) before returning a page." } ], "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 (repeat the parameter for several: `features=hd&features=subtitles`). 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, Markdown links are stripped from the content.", "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 } ], "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" } } } }, "206": { "description": "Transcript Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Upgrade Required", "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": "getTranscript", "parameters": [ { "in": "query", "name": "url", "schema": { "type": "string", "format": "uri", "description": "Video URL from any supported platform (YouTube, TikTok, Twitter, Instagram, Facebook) or a direct media 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(transcriptResult);\n\nif ('jobId' in transcriptResult) {\n // Check job result\n const result = await supadata.transcript.getJobStatus(transcriptResult.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" } } } }, "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": "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" } } } }, "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": "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, or a direct media file URL. 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." } } } }