# Transcript Source: https://docs.supadata.ai/api-reference/endpoint/transcript/transcript v1-openapi GET /transcript Get transcript from a supported video platform (YouTube, TikTok, Instagram, Twitter) 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. # Transcript Result Source: https://docs.supadata.ai/api-reference/endpoint/transcript/transcript-get v1-openapi GET /transcript/{jobId} Get results for a transcript job by job ID. # Crawl Source: https://docs.supadata.ai/api-reference/endpoint/web/crawl v1-openapi POST /web/crawl Create a crawl job to extract content from all pages on a website. # Crawl Status Source: https://docs.supadata.ai/api-reference/endpoint/web/crawl-get v1-openapi GET /web/crawl/{jobId} Get the status and results of a crawl job. # Map Source: https://docs.supadata.ai/api-reference/endpoint/web/map v1-openapi GET /web/map Extract all links found on a whole website. # Scrape Source: https://docs.supadata.ai/api-reference/endpoint/web/scrape v1-openapi GET /web/scrape Extract content from any web page to Markdown format. # Batch Result Source: https://docs.supadata.ai/api-reference/endpoint/youtube/batch-get v1-openapi GET /youtube/batch/{jobId} Get the status and results of a YouTube batch job. # Channel Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel v1-openapi GET /youtube/channel Get metadata for a YouTube channel. # Channel Videos Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel-videos v1-openapi GET /youtube/channel/videos Get video IDs from a YouTube channel. # Playlist Source: https://docs.supadata.ai/api-reference/endpoint/youtube/playlist v1-openapi GET /youtube/playlist Get metadata for a YouTube playlist. # Playlist Videos Source: https://docs.supadata.ai/api-reference/endpoint/youtube/playlist-videos v1-openapi GET /youtube/playlist/videos Get video IDs from a YouTube playlist. # Transcript Source: https://docs.supadata.ai/api-reference/endpoint/youtube/transcript v1-openapi GET /youtube/transcript 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. # Transcript Batch Source: https://docs.supadata.ai/api-reference/endpoint/youtube/transcript-batch v1-openapi POST /youtube/transcript/batch Create a batch job to get transcripts of multiple YouTube videos # Translate Transcript Source: https://docs.supadata.ai/api-reference/endpoint/youtube/translation v1-openapi GET /youtube/transcript/translate Translate YouTube video transcript into different languages. # Video Batch Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-batch v1-openapi POST /youtube/video/batch Create a batch job to fetch metadata of multiple YouTube videos # Video Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get v1-openapi GET /youtube/video Get metadata for a YouTube video. # Introduction Source: https://docs.supadata.ai/api-reference/introduction Supadata API Reference ## Features Get transcript from YouTube, TikTok, Instagram, X (Twitter) or a file. Get YouTube video, channel, playlist metadata. Extract content from any website in markdown format. ## Base URL All requests contain the following base URL: ```sh https://api.supadata.ai/v1 ``` ## Authentication For authentication, it's required to include a `x-api-key` header. ```sh x-api-key: {YOUR_API_KEY} ``` ## Response codes Supadata employs conventional HTTP status codes to signify the outcome of your requests. Typically, 2xx HTTP status codes denote success, 4xx codes represent failures related to the user, and 5xx codes signal infrastructure problems. | Status | Description | | ------ | -------------------------------------------- | | 200 | Request was successful. | | 400 | Verify the correctness of the parameters. | | 401 | The API key was not provided. | | 402 | Payment required. | | 404 | The requested resource could not be located. | | 429 | A plan limit has been surpassed. | | 5xx | Signifies a server error with Supadata. | Refer to the [Error Codes](/errors) section for a detailed explanation of all potential API errors. ## Rate limit The Supadata API has a rate limit to ensure the stability and reliability of the service. The rate limit is applied to all endpoints and is based on the number of requests made within a specific time frame and your current subscription plan. When you exceed the rate limit, you will receive a 429 response code. # Internal Error Source: https://docs.supadata.ai/errors/internal-error An internal server error occurred while processing your request. Explanation of the error and how to fix it. An internal server error occurred while processing your request. This is a server-side error that indicates something went wrong on our end. ```json { "error": "internal-error", "message": "Internal Error", "details": "An internal server error occurred", "documentationUrl": "https://supadata.ai/documentation/errors/internal-error" } ``` ## Reasons and how to fix This error occurs when there's an unexpected issue during request processing on our servers. Possible reasons include: * Server-side processing error: an unexpected error occurred while processing the request. * Database connection issues: temporary database connectivity or network problems. * Service dependencies issues: one of our service dependencies is temporarily unavailable. ### To fix 1. Retry your request after a few moments 2. If the error persists, try with a different request payload 3. Check if the service status page indicates any ongoing issues ### Reach out to support If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible. # Invalid Request Source: https://docs.supadata.ai/errors/invalid-request It is an API error returned when the API fails to serve the request due to invalid request parameters. It is an API error returned when the API fails to serve the request due to invalid request parameters. ```json { "error": "invalid-request", "message": "Invalid request", "details": "Required parameters are missing from the request", "documentationUrl": "https://supadata.ai/documentation/errors/invalid-request" } ``` ## Reasons and how to fix ### Invalid request parameters The most common reason for the `invalid-request` error is that one or more of the request parameters are invalid or missing. To fix this, ensure that all required parameters are included in the request and that they are correctly formatted and valid. ### Missing required parameters If required parameters are missing from the request, this will trigger the `invalid-request` error. To fix this, ensure that all mandatory parameters are provided in the request. Refer to the API documentation for a list of required parameters. ### Incorrect data types Providing parameters with incorrect data types (e.g., a string instead of an integer) can lead to this error. To fix this, verify that the data types of all parameters match the expected types as specified in the API documentation. ### Parameter value constraints Some parameters may have constraints on their values (e.g., minimum or maximum length, specific formats). Violating these constraints will result in this error. To fix this, check the constraints for each parameter in the API documentation and ensure that the provided values comply with these constraints. ### Syntax errors Syntax errors in the request, such as missing commas or brackets in JSON, can make the request invalid. To fix this, carefully review the syntax of your request and correct any errors. Using a JSON validator can help identify syntax issues. ### Reach out to support If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible. # Limit Exceeded Source: https://docs.supadata.ai/errors/limit-exceeded You have exceeded the allowed request rate or quota limits. Explanation of the error and how to fix it. You have exceeded the allowed request rate or quota limits. This error occurs when you've reached the maximum number of requests allowed for your current plan or time period. ```json { "error": "limit-exceeded", "message": "Limit Exceeded", "details": "You have exceeded the allowed request rate or quota limits", "documentationUrl": "https://supadata.ai/documentation/errors/limit-exceeded" } ``` ## Reasons and how to fix ### Rate limit exceeded You've made too many requests in a short time period. To fix this, make sure to not call the API more often than the rate limit on your plan allows. Implement rate limiting in your application and consider batching multiple requests into a single call using our batch endpoints. ### Quota limit reached You've reached your plan's monthly quota limit. To fix this, check your usage in the dashboard and consider upgrading your plan for higher limits, enable Auto Recharge, or wait for the next billing cycle. ### Reach out to support If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible. # Error Codes Source: https://docs.supadata.ai/errors/list A comprehensive list of all possible error codes you might encounter when using the Supadata API. Below is a comprehensive list of all possible error codes you might encounter when using the Supadata API. Each error includes a description, HTTP status code, and a link to detailed documentation about how to handle it. ## Error Reference Table | Error Code | Description | HTTP Status | | -------------------------------------------------------- | ---------------------------------------------------------- | ----------- | | [Invalid Request](/errors/invalid-request) | The request is invalid or malformed | 400 | | [Unauthorized](/errors/unauthorized) | The request is unauthorized. Please check your API key | 401 | | [Upgrade Required](/errors/upgrade-required) | This feature is not available on your current plan | 402 | | [Not Found](/errors/not-found) | The requested item could not be found | 404 | | [Limit Exceeded](/errors/limit-exceeded) | You have exceeded the allowed request rate or quota limits | 429 | | [Transcript Unavailable](/errors/transcript-unavailable) | No transcript is available for this video | 206 | | [Internal Error](/errors/internal-error) | An internal server error occurred | 500 | ## Error Response Format All errors follow a consistent JSON response format: ```json { "error": "error-code", "message": "Human readable error message", "details": "Detailed explanation of the error", "documentationUrl": "https://supadata.ai/errors/error-code" } ``` # Not Found Source: https://docs.supadata.ai/errors/not-found The requested resource could not be found. Explanation of the error and how to fix it. The requested resource could not be found. This error occurs when you try to access a resource that doesn't exist or has been removed. ```json { "error": "not-found", "message": "Not Found", "details": "The requested item could not be found", "documentationUrl": "https://supadata.ai/documentation/errors/not-found" } ``` ## Reasons and how to fix ### Resource doesn't exist or was moved The most common reason for this error is that the resource you're trying to access (eg. YouTube video) doesn't exist, was deleted, or was moved to a different location. To fix this: 1. Double-check the resource identifier (ID, URL, etc.) 2. Verify that the resource hasn't been deleted or moved to a different location 3. Ensure you're using the correct API endpoint ### Incorrect API endpoint The error might occur if you're using an incorrect path to access the Supadata API To fix this, review the API documentation for the correct endpoint structure and make sure you're using the correct path. ### Reach out to support If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible. # Transcript Unavailable Source: https://docs.supadata.ai/errors/transcript-unavailable No transcript is available for this video. Explanation of the error and how to fix it. No transcript is available for this video. This error occurs when you try to access a transcript for a YouTube, TikTok, Instagram or X (Twitter) video that doesn't have one available. ```json { "error": "transcript-unavailable", "message": "Transcript Unavailable", "details": "No transcript is available for this video", "documentationUrl": "https://supadata.ai/documentation/errors/transcript-unavailable" } ``` ## Reasons and how to fix ### Video has no captions The YouTube, TikTok, Instagram or X (Twitter) video doesn't have any captions or subtitles available. To fix this: 1. Use the [`/transcript`](/get-transcript) endpoint with `mode=generate` or `mode=auto` option to generate captions for the video 2. Consider using a different video that has captions ### Reach out to support If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible. # Unauthorized Source: https://docs.supadata.ai/errors/unauthorized The request is unauthorized. Explanation of the error and how to fix it. The request is unauthorized. This error occurs when your Supadata API key is not provided, is invalid or expired. ```json { "error": "unauthorized", "message": "Unauthorized", "details": "The request is unauthorized. Please check your API key.", "documentationUrl": "https://supadata.ai/documentation/errors/unauthorized" } ``` ## Reasons and how to fix ### Supadata API key not provided The error might occur if you haven't included the Supadata API key in your request. To fix this: 1. Ensure you're including the Supadata API key in the request headers 2. Verify the header name is correct (`x-api-key: YOUR_API_KEY` where `YOUR_API_KEY` is your API key from the dashboard) 3. Check if your API client is properly configured to send the key ### Invalid API key The most common reason for this error is that the API key you're using is invalid. To fix this: 1. Verify that you're using the correct API key 2. Ensure there are no extra spaces or special characters in the key ### Expired API key Your API key might have expired. To fix this: 1. Check your API key's expiration date in the Supadata dashboard 2. Generate a new API key if necessary 3. Update your application with the new key ### Reach out to support If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible. # Upgrade Required Source: https://docs.supadata.ai/errors/upgrade-required This feature is not available on your current plan. Explanation of the error and how to fix it. This feature is not available on your current plan. This error occurs when you try to access a feature or endpoint that requires a higher tier subscription. ```json { "error": "upgrade-required", "message": "Upgrade Required", "details": "This feature is not available on your current plan. Upgrade your plan to access it.", "documentationUrl": "https://supadata.ai/documentation/errors/upgrade-required" } ``` ## Reasons and how to fix ### Feature not available in current plan The feature you're trying to use is only available in higher-tier plans. To fix this: 1. Review the feature availability in our pricing page 2. Compare your current plan with available upgrades 3. Consider upgrading to a plan that includes the feature ### Reach out to support If you continue to face issues or need further assistance, please reach out to [support@supadata.ai](mailto:support@supadata.ai), and we will assist you as soon as possible. # Transcript Source: https://docs.supadata.ai/get-transcript Use this API endpoint to fetch text transcript from a video hosted on YouTube, TikTok, Instagram, X (Twitter) or a public file URL. ## Quick Start ### Request ```js Node import { Supadata } from "@supadata/js"; // Initialize the client const supadata = new Supadata({ apiKey: "YOUR_API_KEY", }); // Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter)) or file const transcriptResult = await supadata.transcript({ url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ", lang: "en", // optional text: true, // optional: return plain text instead of timestamped chunks mode: "auto", // optional: 'native', 'auto', or 'generate' }); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") transcript = supadata.transcript( url="https://x.com/SpaceX/status/1481651037291225113", lang="en", # Optional: preferred language text=True, # Optional: return plain text instead of timestamped chunks mode="auto" # Optional: "native", "auto", or "generate" ) ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/transcript?url=https://youtu.be/dQw4w9WgXcQ' \ -H 'x-api-key: YOUR_API_KEY' ``` ### Response ```json { "content": "Never gonna give you up, never gonna let you down...", "lang": "en", "availableLangs": ["en", "es", "zh-TW"] } ``` ## Specification ### Endpoint `GET https://api.supadata.ai/v1/transcript` Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key). ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | string | Yes | URL of the video to get transcript from. Must be either YouTube, TikTok, Instagram, X (Twitter) or a public file URL. It is recommended to encode the URL before sending it as a query parameter. | | lang | string | No | Preferred language code of the transcript (ISO 639-1). See [Languages](#languages). | | text | boolean | No | When true, returns plain text transcript. Default: false | | chunkSize | number | No | Maximum characters per transcript chunk (only when text=false) | | mode | string | No | 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`. Default: `auto`. | To fetch only existing transcripts and avoid costs tied to AI generation, use `mode=native`. ### Response Format The API can return either a transcript result directly (HTTP 200) or a job ID for asynchronous processing (HTTP 202). For large videos that require processing time, the API returns HTTP 202 with a job ID. Use the `/transcript/{jobId}` endpoint to poll for results. **Immediate transcript response (HTTP 200):** When `text=true`: ```typescript { "content": string, "lang": string // ISO 639-1 language code "availableLangs": string[] // List of available languages } ``` When `text=false`: ```typescript { "content": [ { "text": string, // Transcript segment "offset": number, // Start time in milliseconds "duration": number, // Duration in milliseconds "lang": string // ISO 639-1 language code of chunk } ], "lang": string // ISO 639-1 language code of transcript "availableLangs": string[] // List of available languages } ``` **Asynchronous job response (HTTP 202):** ```typescript { "jobId": string // Job ID for checking results } ``` ### Getting Job Results When the API returns a job ID, you can poll for results using the job ID endpoint: ```js Node import { Supadata } from "@supadata/js"; // Check if we got a transcript directly or a job ID for async processing if ("jobId" in transcriptResult) { // For large files, we get a job ID and need to poll for results const jobResult = await supadata.transcript.getJobStatus( transcriptResult.jobId ); if (jobResult.status === "completed") { console.log(jobResult.content); } else if (jobResult.status === "failed") { console.error(jobResult.error); } else { console.log("Job status:", jobResult.status); } } else { // For smaller files or native transcripts, we get the result directly console.log("Transcript:", transcriptResult); } ``` ```python Python # For immediate results if hasattr(transcript, 'content'): print(f"Transcript: {transcript.content}") print(f"Language: {transcript.lang}") else: # For async processing (large files) print(f"Processing started with job ID: {transcript.job_id}") # Poll for results using existing batch.get_batch_results method ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/transcript/123e4567-e89b-12d3-a456-426614174000' \ -H 'x-api-key: YOUR_API_KEY' ``` #### Response ```json { "status": "completed", "content": "Never gonna give you up, never gonna let you down...", "lang": "en", "availableLangs": ["en", "es", "zh-TW"] } ``` #### Job Status Values | Status | Description | | --------- | ----------------------------------------------- | | queued | The job is in the queue waiting to be processed | | active | The job is currently being processed | | completed | The job has finished and results are available | | failed | The job failed due to an error | Poll the job status endpoint until the status is either "completed" or "failed". The `result` field will contain the transcript data when status is "completed", or the `error` field will contain error details when status is "failed". ### Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. ### Supported URL Formats `url` parameter supports the following: * YouTube video URL, e.g. `https://www.youtube.com/watch?v=1234567890` * TikTok video URL, e.g. `https://www.tiktok.com/@username/video/1234567890` * X (Twitter) video URL, e.g. `https://x.com/username/status/1234567890` * Instagram video URL, e.g. `https://instagram.com/reel/1234567890/` * Publicly accessible file URL, e.g. `https://bucket.s3.eu-north-1.amazonaws.com/file.mp4` ### File Transcripts When `url` is a file URL, the endpoint supports the following file formats: * MP4 * WEBM * MP3 * FLAC * MPEG * M4A * OGG * WAV The maximum file size is 1 GB. There is no limit on the video duration. ## Languages The endpoint supports multiple languages. The `lang` parameter is used to specify the preferred language of the transcript. If the video does not have a transcript in the preferred language, the endpoint will return a transcript in the first available language and a list of other available languages. It is then possible to make another request to get the transcript in your chosen fallback language. When `mode = generate`, the `lang` parameter is ignored and the transcript is generated in the language of the video. ## Pricing * 1 native transcript = 1 credit * 1 generated transcript minute = 2 credits # Introduction Source: https://docs.supadata.ai/index Welcome to the Supadata documentation. Our API provides powerful tools for extracting web content. ## Overview Supadata offers three main services: * Video Transcripts - Extract transcripts from YouTube, TikTok, Instagram, X (Twitter) and video files * Web Reader - Extract content from any website, crawl pages and extract structured data * YouTube Metadata - Extract video, channel and playlist metadata ## Getting an API Key All requests to Supadata require authentication using an API key. The same key also works with the SDKs and no-code integrations. To get your API key: 1. Sign up for an account at [dash.supadata.ai](https://dash.supadata.ai) 2. Your API key will be generated automatically during onboarding and available in the dashboard ## Integrations and SDKs This documentation provides examples for how to use the Supadata API and its various parameters. We also offer the following SDKs and integrations: * [JavaScript SDK](https://github.com/supadata-ai/js) * [Python SDK](https://github.com/supadata-ai/py) * Make, Zapier, n8n, Active Pieces: [See here](https://supadata.ai/nocode) ## Documentation for AI If you're working with an AI assistant or vibe coding, we recommend using the "Copy Page" dropdown in top right corner of each page to get AI-ready documentation. Alternatively, give your assistant links to [llms.txt](/llms.txt) or [llms-full.txt](/llms-full.txt). ## Rate Limits API requests are rate-limited based on your subscription plan. Current limits are shown on the [pricing page](https://supadata.ai/pricing). It is possible to increase rate limits upon request. ## API Usage ### Authentication All API requests require authentication using an API key. Include your API key in the request headers: ```bash curl -H "x-api-key: YOUR_API_KEY" https://api.supadata.ai/v1/... ``` Never share your API key or commit it to version control. Use environment variables to store your API key securely. Only access the API from a secure server environment. ### Base URL All API endpoints use the following base URL: `https://api.supadata.ai/v1` ### Response Format All API responses are returned in JSON format. # Node Source: https://docs.supadata.ai/sdks/node Supadata Node SDK is a wrapper around the Supadata API to help you easily turn videos into transcripts and websites into markdown. ## Installation To install the Supadata Node SDK, you can use npm (or pnpm, yarn, bun, etc.): ```bash Node npm install @supadata/js ``` ## Usage Get an API key from [dash.supadata.ai](https://dash.supadata.ai), then use it with the SDK. Here's an example of how to use the SDK with error handling: ```js Node import { Crawl, CrawlJob, JobResult, Map, Scrape, Supadata, Transcript, TranscriptOrJobId, YoutubeChannel, YoutubePlaylist, YoutubeVideo, } from "@supadata/js"; // Initialize the client const supadata = new Supadata({ apiKey: "YOUR_API_KEY", }); // Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter)) or file const transcriptResult = await supadata.transcript({ url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ", lang: "en", // optional text: true, // optional: return plain text instead of timestamped chunks mode: "auto", // optional: 'native', 'auto', or 'generate' }); // Check if we got a transcript directly or a job ID for async processing if ("jobId" in transcriptResult) { // For large files, we get a job ID and need to poll for results console.log(`Started transcript job: ${transcriptResult.jobId}`); // Poll for job status const jobResult = await supadata.transcript.getJobStatus( transcriptResult.jobId ); if (jobResult.status === "completed") { console.log("Transcript:", jobResult.content); } else if (jobResult.status === "failed") { console.error("Transcript failed:", jobResult.error); } else { console.log("Job status:", jobResult.status); // 'queued' or 'active' } } else { // For smaller files, we get the transcript directly console.log("Transcript:", transcriptResult); } ``` ### Transcripts Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter)) or file ```js Node import { Supadata } from "@supadata/js"; // Initialize the client const supadata = new Supadata({ apiKey: "YOUR_API_KEY", }); // Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter)) or file const transcriptResult = await supadata.transcript({ url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ", lang: "en", // optional text: true, // optional: return plain text instead of timestamped chunks mode: "auto", // optional: 'native', 'auto', or 'generate' }); ``` ### YouTube Get YouTube video, channel, playlist metadata. ```js Node const transcript: Transcript = await supadata.youtube.transcript({ url: 'https://youtu.be/dQw4w9WgXcQ', }); // Translate YouTube transcript const translated: Transcript = await supadata.youtube.translate({ videoId: 'dQw4w9WgXcQ', lang: 'es', }); // Get a YouTube Video metadata const video: YoutubeVideo = await supadata.youtube.video({ id: 'dQw4w9WgXcQ', // can be url or video id }); // Get a YouTube channel metadata const channel: YoutubeChannel = await supadata.youtube.channel({ id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle }); // Get a list of video IDs from a YouTube channel const channelVideos: VideoIds = await supadata.youtube.channel.videos({ id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle type: 'all', // 'video', 'short', 'live', 'all' limit: 10, }); // Get the metadata of a YouTube playlist const playlist: YoutubePlaylist = await supadata.youtube.playlist({ id: 'PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI', // can be url or playlist id }); // Get a list of video IDs from a YouTube playlist const playlistVideos: VideoIds = await supadata.youtube.playlist.videos({ id: 'https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc', // can be url or playlist id limit: 10, }); // Start a YouTube transcript batch job const transcriptBatch = await supadata.youtube.transcript.batch({ videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'], // playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' // alternatively // channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively lang: 'en', }); console.log(`Started transcript batch job: ${transcriptBatch.jobId}`); // Start a YouTube video metadata batch job const videoBatch = await supadata.youtube.video.batch({ videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0', 'L_jWHffIx5E'], // playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' // alternatively // channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively }); console.log(`Started video batch job: ${videoBatch.jobId}`); // Get results for a batch job (poll until status is 'completed' or 'failed') const batchResults = await supadata.youtube.batch.getBatchResults( transcriptBatch.jobId ); // or videoBatch.jobId if (batchResults.status === 'completed') { console.log('Batch job completed:', batchResults.results); console.log('Stats:', batchResults.stats); } else { console.log('Batch job status:', batchResults.status); } ``` ### Web Scrape and crawl web content. ```js Node const webContent: Scrape = await supadata.web.scrape('https://supadata.ai'); // Map website URLs const siteMap: Map = await supadata.web.map('https://supadata.ai'); // Crawl website const crawl: JobId = await supadata.web.crawl({ url: 'https://supadata.ai', limit: 10, }); // Get crawl job results const crawlResults: CrawlJob = await supadata.web.getCrawlResults(crawl.jobId); ``` ### Error Handling The SDK throws `SupadataError` for API-related errors. You can catch and handle these errors as follows: ```js Node import { SupadataError } from '@supadata/js'; try { const transcript = await supadata.youtube.transcript({ videoId: 'INVALID_ID', }); } catch (e) { if (e instanceof SupadataError) { console.error(e.error); // e.g., 'video-not-found' console.error(e.message); // Human readable error message console.error(e.details); // Detailed error description console.error(e.documentationUrl); // Link to error documentation (optional) } } ``` # Overview Source: https://docs.supadata.ai/sdks/overview Supadata SDKs are wrappers around the Supadata API to help you easily extract data from websites. ## Official SDKs Explore the Python SDK for Supadata. Explore the Node SDK for Supadata. # Python Source: https://docs.supadata.ai/sdks/python Supadata Python SDK is a wrapper around the Supadata API to help you easily turn videos into transcripts and websites into markdown. ## Installation To install the Supadata Python SDK, you can use pip: ```bash Python pip install supadata ``` ## Usage Get an API key from [dash.supadata.ai](https://dash.supadata.ai), then use it with the SDK. Here's an example of how to use the SDK: ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") # Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter), file URLs) transcript = supadata.transcript( url="https://x.com/SpaceX/status/1481651037291225113", lang="en", # Optional: preferred language text=True, # Optional: return plain text instead of timestamped chunks mode="auto" # Optional: "native", "auto", or "generate" ) # For immediate results if hasattr(transcript, 'content'): print(f"Transcript: {transcript.content}") print(f"Language: {transcript.lang}") else: # For async processing (large files) print(f"Processing started with job ID: {transcript.job_id}") # Poll for results using existing batch.get_batch_results method ``` ### Transcripts Get transcript from any supported platform (YouTube, TikTok, Instagram, X (Twitter), file URLs) ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") transcript = supadata.transcript( url="https://x.com/SpaceX/status/1481651037291225113", lang="en", # Optional: preferred language text=True, # Optional: return plain text instead of timestamped chunks mode="auto" # Optional: "native", "auto", or "generate" ) ``` ### YouTube Get YouTube video, channel, playlist metadata. ```python Python # Get YouTube transcript with Spanish language preference transcript = supadata.youtube.transcript(video_id="dQw4w9WgXcQ", lang="es") print(f"Got transcript {transcript.content}") # Translate YouTube transcript to Spanish translated = supadata.youtube.translate( video_id="dQw4w9WgXcQ", lang="es" ) print(f"Got translated transcript in {translated.lang}") # Get plain text transcript text_transcript = supadata.youtube.transcript( video_id="dQw4w9WgXcQ", text=True ) print(text_transcript.content) # Get Video Metadata video = supadata.youtube.video(id="https://youtu.be/dQw4w9WgXcQ") # can be url or video id print(f"Video: {video}") # Get Channel Metadata channel = supadata.youtube.channel(id="https://youtube.com/@RickAstleyVEVO") # can be url, channel id, handle print(f"Channel: {channel}") # Get video IDs from a YouTube channel channel_videos = supadata.youtube.channel.videos( id="RickAstleyVEVO", # can be url, channel id, or handle type="all", # 'all', 'video', 'short', or 'live' limit=50 ) print(f"Regular videos: {channel_videos.video_ids}") print(f"Shorts: {channel_videos.short_ids}") print(f"Live: {channel_videos.live_ids}") # Get Playlist metadata playlist = supadata.youtube.playlist(id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc") # can be url or playlist id print(f"Playlist: {playlist}") # Get video IDs from a YouTube playlist playlist_videos = supadata.youtube.playlist.videos( id="https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", # can be url or playlist id limit=50 ) print(f"Regular videos: {playlist_videos.video_ids}") print(f"Shorts: {playlist_videos.short_ids}") print(f"Live: {playlist_videos.live_ids}") # Batch Operations transcript_batch_job = supadata.youtube.transcript.batch( video_ids=["dQw4w9WgXcQ", "xvFZjo5PgG0"], # playlist_id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", # alternatively # channel_id="UC_9-kyTW8ZkZNDHQJ6FgpwQ", # alternatively lang="en", # Optional: specify preferred transcript language limit=100 # Optional: limit for playlist/channel ) print(f"Started transcript batch job: {transcript_batch_job.job_id}") # Start a batch job to get video metadata for a playlist video_batch_job = supadata.youtube.video.batch( playlist_id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", limit=50 ) print(f"Started video metadata batch job: {video_batch_job.job_id}") # Get the results of a batch job (poll until status is 'completed' or 'failed') batch_results = supadata.youtube.batch.get_batch_results(job_id=transcript_batch_job.job_id) print(f"Job status: {batch_results.status}") print(f"Stats: {batch_results.stats.succeeded}/{batch_results.stats.total} videos processed") print(f"First result: {batch_results.results[0].video_id if batch_results.results else 'No results yet'}") ``` ### Web Scrape and crawl web content. ```python Python web_content = supadata.web.scrape("https://supadata.ai") print(f"Page title: {web_content.name}") print(f"Page content: {web_content.content}") # Map website URLs site_map = supadata.web.map("https://supadata.ai") print(f"Found {len(site_map.urls)} URLs") # Start a crawl job crawl_job = supadata.web.crawl( url="https://supadata.ai", limit=100 # Optional: limit the number of pages to crawl ) print(f"Started crawl job: {crawl_job.job_id}") # Get crawl results # This automatically handles pagination and returns all pages try: pages = supadata.web.get_crawl_results(job_id=crawl_job.job_id) for page in pages: print(f"Crawled page: {page.url}") print(f"Page title: {page.name}") print(f"Content: {page.content}") except SupadataError as e: print(f"Crawl job failed: {e}") ``` ### Error Handling The SDK uses custom `SupadataError` exceptions that provide structured error information: ```python Python from supadata.errors import SupadataError try: transcript = supadata.youtube.transcript(video_id="INVALID_ID") except SupadataError as error: print(f"Error code: {error.error}") print(f"Error message: {error.message}") print(f"Error details: {error.details}") if error.documentation_url: print(f"Documentation: {error.documentation_url}") ``` # Crawl Source: https://docs.supadata.ai/web/crawl Crawl a whole website and get content of all pages on it. Crawling is a long running task. To get the content of a crawl, you first create a crawl job and then check the results of the job. ## Request ```js Node import { Supadata, JobId } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); // Crawl website const crawl: JobId = await supadata.web.crawl({ url: 'https://supadata.ai', limit: 10, }); console.log(`Started crawl job: ${crawl.jobId}`); ``` ```python Python from supadata import Supadata # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") # Start a crawl job crawl_job = supadata.web.crawl( url="https://supadata.ai", limit=100 # Optional: limit the number of pages to crawl ) print(f"Started crawl job: {crawl_job.job_id}") ``` ```bash cURL curl -X POST 'https://api.supadata.ai/v1/web/crawl' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"url": "https://supadata.ai", "limit": 100}' ``` The crawler will follow only the child links. For example, if you crawl `https://supadata.ai/blog`, the crawler will follow links like `https://supadata.ai/blog/article-1` , but not `https://supadata.ai/about`. To crawl the whole website, provide the top URL (ie `https://supadata.ai`) as the URL to crawl. ## Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------- | | url | string | Yes | URL of the webpage to scrape | | limit | number | No | Maximum number of pages to crawl. Defaults to 100. | ## Response ```json { "jobId": "string" // The ID of the crawl job } ``` ## Results After starting a crawl job, you can check the status of it. If the job is completed, you can get the results of the crawl. The results can be paginated for large crawls. In such cases, the response will contain a `next` field which you can use to get the next page of results. ### Crawl Job ```js Node import { Supadata } from "@supadata/js"; const supadata = new Supadata("YOUR_API_KEY"); // Check the status of a crawl job const crawlResult = await supadata.web.crawl.getJobStatus(jobId); if (crawlResult.status === "completed") { console.log("Crawl job completed successfully!"); console.log(`Total pages crawled: ${crawlResult.pages.length}`); // Process each page crawlResult.pages.forEach((page, index) => { console.log(`Page ${index + 1}: ${page.name}`); console.log(`URL: ${page.url}`); console.log(`Description: ${page.description}`); console.log(`Content preview: ${page.content.substring(0, 100)}...`); console.log("---"); }); // Handle pagination if there are more results if (crawlResult.next) { console.log("More results available. Next page URL:", crawlResult.next); } } else if (crawlResult.status === "failed") { console.error("Crawl job failed:", crawlResult.error); } else { console.log("Job status:", crawlResult.status); } ``` ```python Python from supadata import Supadata supadata = Supadata("YOUR_API_KEY") # Check the status of a crawl job crawl_result = supadata.web.crawl.get_job_status(job_id) if crawl_result.status == "completed": print("Crawl job completed successfully!") print(f"Total pages crawled: {len(crawl_result.pages)}") # Process each page for i, page in enumerate(crawl_result.pages): print(f"Page {i + 1}: {page.name}") print(f"URL: {page.url}") print(f"Description: {page.description}") print(f"Content preview: {page.content[:100]}...") print("---") # Handle pagination if there are more results if hasattr(crawl_result, 'next') and crawl_result.next: print(f"More results available. Next page URL: {crawl_result.next}") elif crawl_result.status == "failed": print(f"Crawl job failed: {crawl_result.error}") else: print(f"Job status: {crawl_result.status}") ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/web/crawl/123e4567-e89b-12d3-a456-426614174000' \ -H 'x-api-key: YOUR_API_KEY' ``` ### Crawl Results ```json { "status": "string", // The status of the crawl job: 'scraping', 'completed', 'failed' or 'cancelled' "pages": [ // If job is completed, contains list of pages that were crawled { "url": "string", // The URL that was scraped "content": "string", // The markdown content extracted from the URL "name": "string", // The title of the webpage "description": "string" // A description of the webpage } ], "next": "string" // Large crawls will be paginated. Call this endpoint to get the next page of results } ``` ## Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. Respect robots.txt and website terms of service when scraping web content. ## Pricing * 1 crawl request = 1 credit * 1 crawled page = 1 credit # Map Source: https://docs.supadata.ai/web/map Scan a whole website and get URLs on it. Can be used to create a sitemap or run a crawler to fetch content of all pages of a destination. ## Request ```js Node import { Supadata, Map } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); const siteMap: Map = await supadata.web.map('https://supadata.ai'); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") site_map = supadata.web.map("https://supadata.ai") print(f"Found {len(site_map.urls)} URLs") ``` ```bash cURL curl 'https://api.supadata.ai/v1/web/map?url=https://example.com' \ -H 'x-api-key: YOUR_API_KEY' ``` ## Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------- | | url | string | Yes | URL of the website to map | ## Response Format ```json { "urls": [ "string" // List of URLs found on the webpage ] } ``` ## Pricing * 1 map request = 1 credit # Scrape Source: https://docs.supadata.ai/web/scrape Extract content from any web page using our powerful scraping API. ## Request ```js Node import { Supadata, Scrape } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); const webContent: Scrape = await supadata.web.scrape('https://supadata.ai'); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") web_content = supadata.web.scrape("https://supadata.ai") print(f"Page title: {web_content.name}") print(f"Page content: {web_content.content}") ``` ```bash cURL curl 'https://api.supadata.ai/v1/web/scrape?url=https://example.com' \ -H 'x-api-key: YOUR_API_KEY' ``` ## Query Parameters | Parameter | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | url | string | Yes | URL of the webpage to scrape | | noLinks | boolean | No | Whether to include Markdown links in the response | | lang | string | No | What language to request the content in, if the website supports multiple languages. ISO 639-1 code. Default: en | ## Response Format ```json { "url": "string", // The URL that was scraped "content": "string", // The content extracted from the URL "name": "string", // The name of the webpage "description": "string", // A description of the webpage "ogUrl": "string", // Open Graph URL for the webpage "countCharacters": "number", // The number of characters in the content "urls": [ "string" // List of URLs found on the webpage ] } ``` ## Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. Respect robots.txt and website terms of service when scraping web content. ## Pricing * 1 transcript request = 1 credit # Batch Source: https://docs.supadata.ai/youtube/batch Get multiple transcripts or video metadata from YouTube videos in a playlist, channel or list of URLs. The batch endpoints allow you to process multiple YouTube videos in a single request. This is useful for analyzing entire playlists or channels, or for processing a list of videos. Batch operations are asynchronous and return a job ID that can be used to check the results. This feature is available only on paid plans. ## Supported Source Types All batch endpoints support the following source types: * List of video URLs or IDs * Playlist URL or ID * Channel URL, handle, or ID ## Batch Endpoints ### Transcript Batch #### Request ```js Node import { Supadata, } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); // Start a YouTube transcript batch job const transcriptBatch = await supadata.youtube.transcript.batch({ videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'], // playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' // alternatively // channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively lang: 'en', }); console.log(`Started transcript batch job: ${transcriptBatch.jobId}`); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") transcript_batch_job = supadata.youtube.transcript.batch( video_ids=["dQw4w9WgXcQ", "xvFZjo5PgG0"], # playlist_id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", # alternatively # channel_id="UC_9-kyTW8ZkZNDHQJ6FgpwQ", # alternatively lang="en", # Optional: specify preferred transcript language limit=100 # Optional: limit for playlist/channel ) print(f"Started transcript batch job: {transcript_batch_job.job_id}") ``` ```bash cURL curl -X POST 'https://api.supadata.ai/v1/youtube/transcript/batch' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "videoIds": [ "dQw4w9WgXcQ", "https://www.youtube.com/watch?v=xvFZjo5PgG0" ], "lang": "en", "text": true }' ``` #### Parameters | Parameter | Type | Required | Description | | ---------- | ------- | ------------------------ | ------------------------------------------------------------------------------------------------ | | videoIds | array | One of these is required | Array of YouTube video IDs or URLs | | playlistId | string | One of these is required | YouTube playlist URL or ID | | channelId | string | One of these is required | YouTube channel URL, handle or ID | | limit | number | No | Maximum number of videos to process (when using playlistId or channelId). Default: 10, Max: 5000 | | lang | string | No | Preferred language code for transcripts (ISO 639-1) | | text | boolean | No | When true, returns plain text transcript. Default: false | #### Response ```json { "jobId": "123e4567-e89b-12d3-a456-426614174000" } ``` ### Video Metadata Batch #### Request ```js Node import { Supadata, } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); // Start a YouTube video metadata batch job const videoBatch = await supadata.youtube.video.batch({ playlistId: 'PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc', limit: 20, // videoIds: ['dQw4w9WgXcQ', 'xvFZjo5PgG0'] // alternatively // channelId: 'UC_9-kyTW8ZkZNDHQJ6FgpwQ' // alternatively }); console.log(`Started video metadata batch job: ${videoBatch.jobId}`); ``` ```python Python from supadata import Supadata # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") video_batch_job = supadata.youtube.video.batch( playlist_id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", limit=20 # video_ids=["dQw4w9WgXcQ", "xvFZjo5PgG0"], # alternatively # channel_id="UC_9-kyTW8ZkZNDHQJ6FgpwQ", # alternatively ) print(f"Started video metadata batch job: {video_batch_job.job_id}") ``` ```bash cURL curl -X POST 'https://api.supadata.ai/v1/youtube/video/batch' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "playlistId": "PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", "limit": 20 }' ``` #### Parameters | Parameter | Type | Required | Description | | ---------- | ------ | ------------------------ | ------------------------------------------------------------------------------------------------ | | videoIds | array | One of these is required | Array of YouTube video IDs or URLs | | playlistId | string | One of these is required | YouTube playlist URL or ID | | channelId | string | One of these is required | YouTube channel URL, handle or ID | | limit | number | No | Maximum number of videos to process (when using playlistId or channelId). Default: 10, Max: 5000 | #### Response ```json { "jobId": "123e4567-e89b-12d3-a456-426614174000" } ``` ## Getting Batch Results Once you've created a batch job, you can check its status and retrieve results using the job ID. ### Check Batch Job Status `GET /v1/youtube/batch/{jobId}` - Get the status and results of a batch job. #### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------- | | jobId | string | Yes | The ID of the batch job | #### Request ```js Node import { Supadata } from "@supadata/js"; const supadata = new Supadata("YOUR_API_KEY"); // Check the status of a batch job const batchResult = await supadata.youtube.batch.getJobStatus(jobId); if (batchResult.status === "completed") { console.log("Batch job completed successfully!"); console.log(`Total videos: ${batchResult.stats.total}`); console.log(`Succeeded: ${batchResult.stats.succeeded}`); console.log(`Failed: ${batchResult.stats.failed}`); // Process each result batchResult.results.forEach((result, index) => { if (result.transcript) { console.log(`Video ${index + 1}: ${result.videoId}`); console.log(`Transcript: ${result.transcript.content}`); console.log(`Language: ${result.transcript.lang}`); } else if (result.errorCode) { console.log(`Video ${index + 1} failed: ${result.errorCode}`); } }); } else if (batchResult.status === "failed") { console.error("Batch job failed:", batchResult.error); } else { console.log("Job status:", batchResult.status); } ``` ```python Python from supadata import Supadata supadata = Supadata("YOUR_API_KEY") # Check the status of a batch job batch_result = supadata.youtube.batch.get_job_status(job_id) if batch_result.status == "completed": print("Batch job completed successfully!") print(f"Total videos: {batch_result.stats.total}") print(f"Succeeded: {batch_result.stats.succeeded}") print(f"Failed: {batch_result.stats.failed}") # Process each result for i, result in enumerate(batch_result.results): if hasattr(result, 'transcript') and result.transcript: print(f"Video {i + 1}: {result.video_id}") print(f"Transcript: {result.transcript.content}") print(f"Language: {result.transcript.lang}") elif hasattr(result, 'error_code'): print(f"Video {i + 1} failed: {result.error_code}") elif batch_result.status == "failed": print(f"Batch job failed: {batch_result.error}") else: print(f"Job status: {batch_result.status}") ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/youtube/batch/123e4567-e89b-12d3-a456-426614174000' \ -H 'x-api-key: YOUR_API_KEY' ``` #### Response ```json { "status": "completed", "results": [ { "videoId": "dQw4w9WgXcQ", "transcript": { "content": "Never gonna give you up, never gonna let you down...", "lang": "en", "availableLangs": ["en", "es", "fr"] } }, { "videoId": "xvFZjo5PgG0", "errorCode": "transcript-unavailable" } ], "stats": { "total": 2, "succeeded": 1, "failed": 1 }, "completedAt": "2025-04-03T06:59:53.428Z" } ``` ## Batch Job Status The batch job can be in one of the following states: | Status | Description | | --------- | ----------------------------------------------- | | queued | The job is in the queue waiting to be processed | | active | The job is currently being processed | | completed | The job has finished processing all videos | | failed | The job failed due to an error | Batch jobs are processed asynchronously and may take some time to complete, especially for large playlists or channels. You should poll the job status endpoint until the status is either "completed" or "failed". ## Pricing * 1 request to start a batch job = 1 credit * 1 video / transcript in a batch = 1 credit For example, if you start a batch job with 10 videos, you will be charged 11 credits: 1 for the request and 10 for the videos. # Channel Source: https://docs.supadata.ai/youtube/channel Use this API endpoint to fetch metadata from a YouTube channel including name, description, subscriber count, and more. ## Quick Start ### Request ```js Node import { Supadata, YoutubeChannel } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); const channel: YoutubeChannel = await supadata.youtube.channel({ id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle }); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") channel = supadata.youtube.channel(id="https://youtube.com/@RickAstleyVEVO") # can be url, channel id, handle print(f"Channel: {channel}") ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/youtube/channel?id=RickAstleyVEVO' \ -H 'x-api-key: YOUR_API_KEY' ``` ### Response ```json { "id": "UCuAXFkgsw1L7xaCfnd5JJOw", "name": "Rick Astley", "description": "The official Rick Astley YouTube channel", "subscriberCount": 2000000, "videoCount": 100, "thumbnail": "https://yt3.ggpht.com/...", "banner": "https://yt3.ggpht.com/..." } ``` ## Specification ### Endpoint `GET https://api.supadata.ai/v1/youtube/channel` Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key). ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- | | id | string | Yes | YouTube channel URL, handle or ID. See [Supported YouTube URL Formats](/youtube/supported-url-formats). | ## Channel Videos You can also retrieve a list of video IDs from a channel using the [Channel Videos](/youtube/channel-videos) endpoint. ### Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. ### Supported YouTube Identifiers The universal `id` parameter supports various YouTube URL and ID formats. See this [page](/youtube/supported-url-formats) for more details. ## Pricing * 1 channel metadata request = 1 credit # Channel Videos Source: https://docs.supadata.ai/youtube/channel-videos Use this API endpoint to fetch a list of video IDs from a YouTube channel. ## Quick Start ### Request ```js Node import { Supadata, VideoIds } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); const channelVideos: VideoIds = await supadata.youtube.channel.videos({ id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle type: 'all', // 'video', 'short', 'live', 'all' limit: 10, }); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") channel_videos = supadata.youtube.channel.videos( id="RickAstleyVEVO", # can be url, channel id, or handle type="all", # 'all', 'video', 'short', or 'live' limit=50 ) print(f"Regular videos: {channel_videos.video_ids}") print(f"Shorts: {channel_videos.short_ids}") print(f"Live: {channel_videos.live_ids}") ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/youtube/channel/videos?id=RickAstleyVEVO&limit=50' \ -H 'x-api-key: YOUR_API_KEY' ``` ### Response ```json { "videoIds": ["dQw4w9WgXcQ", "xvFZjo5PgG0"], "shortIds": ["xvFZjo5PgG0", "dQw4w9WgXcQ"], "liveIds": ["dQw4w9WgXcQ", "xvFZjo5PgG0"] } ``` ## Specification ### Endpoint `GET https://api.supadata.ai/v1/youtube/channel/videos` Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key). ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | id | string | Yes | YouTube channel URL, handle or ID. See [Supported YouTube URL Formats](/youtube/supported-url-formats). | | limit | number | No | Maximum number of video IDs to return. If `type` = `all`, vertical videos are prioritized. (Default: 30, Max: 5000) | | type | enum | No | `all`, `video`, `short`, `live` (Default: `all`) | When fetching `type: all`, the limit parameter applies to vertical videos first, then Shorts and live videos. For example, if the channel has 100 vertical videos and 100 Shorts, and `limit` is 150, then 100 vertical videos and 50 Shorts will be returned. ### Response Format ```typescript { "videoIds": string[], // List of vertical YouTube video IDs "shortIds": string[], // List of Shorts IDs "liveIds": string[] // List of live video IDs } ``` ### Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. ### Supported YouTube Identifiers The universal `id` parameter supports various YouTube URL and ID formats. See this [page](/youtube/supported-url-formats) for more details. ## Working with Channel Videos After retrieving the list of video IDs, you can: 1. Get metadata for each video using the [Video Metadata](/youtube/video) endpoint 2. Get transcripts for each video using the [Transcript](/get-transcript) endpoint Videos are returned latest first, just like in the "Videos" tab of a YouTube channel. ## Pricing * 1 channel videos request = 1 credit # Transcript Source: https://docs.supadata.ai/youtube/get-transcript Use this API endpoint to fetch text transcript from a YouTube video in various formats and languages. This endpoint will soon be deprecated in favor of the [Universal Transcripts](/get-transcript). Please migrate your workloads. ## Quick Start ### Request ```js Node import { Supadata, Transcript } from "@supadata/js"; // Initialize the client const supadata = new Supadata({ apiKey: "YOUR_API_KEY", }); const transcript: Transcript = await supadata.youtube.transcript({ url: "https://youtu.be/dQw4w9WgXcQ", }); console.log(transcript); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") text_transcript = supadata.youtube.transcript( video_id="dQw4w9WgXcQ", text=True ) print(text_transcript.content) ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/youtube/transcript?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ&text=true' \ -H 'x-api-key: YOUR_API_KEY' ``` ### Response ```json { "content": "Never gonna give you up, never gonna let you down...", "lang": "en", "availableLangs": ["en", "es", "zh-TW"] } ``` ## Specification ### Endpoint `GET https://api.supadata.ai/v1/youtube/transcript` Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key). ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------- | -------- | --------------------------------------------------------------------------------------- | | url | string | Yes\* | YouTube video URL. See [Supported YouTube URL Formats](#supported-youtube-url-formats). | | videoId | string | Yes\* | YouTube video ID. Alternative to URL | | lang | string | No | Preferred language code of the transcript (ISO 639-1). See [Languages](#languages). | | text | boolean | No | When true, returns plain text transcript. Default: false | | chunkSize | number | No | Maximum characters per transcript chunk (only when text=false) | \* Either `url` or `videoId` must be provided ### Response Format **When `text=true`:** ```typescript { "content": string, "lang": string // ISO 639-1 language code "availableLangs": string[] // List of available languages } ``` **When `text=false`:** ```typescript { "content": [ { "text": string, // Transcript segment "offset": number, // Start time in milliseconds "duration": number, // Duration in milliseconds "lang": string // ISO 639-1 language code of chunk } ], "lang": string // ISO 639-1 language code of transcript "availableLangs": string[] // List of available languages } ``` ### Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. ### Supported YouTube URL Formats `url` parameter supports various YouTube URL formats. See this [page](/youtube/supported-url-formats) for more details. ## Languages The endpoint supports multiple languages. The `lang` parameter is used to specify the preferred language of the transcript. If the video does not have a transcript in the preferred language, the endpoint will return a transcript in the first available language and a list of other available languages. It is then possible to make another request to get the transcript in your chosen fallback language. Need to get your transcript in a language not yet supported? Check the [Transcript Translation](/youtube/get-transcript-translation) endpoint. ## Pricing * 1 transcript request = 1 credit # Translation Source: https://docs.supadata.ai/youtube/get-transcript-translation Use this API endpoint to fetch text transcript from a YouTube video in various formats and languages. ## Quick Start ### Request ```js Node import { Supadata, Transcript } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); const translated: Transcript = await supadata.youtube.translate({ videoId: 'dQw4w9WgXcQ', lang: 'es', }); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") translated = supadata.youtube.translate( video_id="dQw4w9WgXcQ", lang="es" ) print(f"Got translated transcript in {translated.lang}") ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/youtube/transcript/translate?videoId=dQw4w9WgXcQ&lang=es&text=true' \ -H 'x-api-key: YOUR_API_KEY' ``` ### Response ```json { "content": "Nunca voy a abandonarte, nunca voy a decepcionarte…", "lang": "es" } ``` This endpoint has longer than usual response times. See [Latency](#latency) for more details. ## Specification ### Endpoint `GET https://api.supadata.ai/v1/youtube/transcript/translate` Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key). ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------- | -------- | --------------------------------------------------------------------------------------- | | url | string | Yes\* | YouTube video URL. See [Supported YouTube URL Formats](#supported-youtube-url-formats). | | videoId | string | Yes\* | YouTube video ID. Alternative to URL. | | lang | string | Yes | ISO 639-1 language code of the translation | | text | boolean | No | When true, returns plain text transcript. Default: false | | chunkSize | number | No | Maximum characters per transcript chunk (only when text=false) | \* Either `url` or `videoId` must be provided ### Response Format **When `text=true`:** ```typescript { "content": string, "lang": string // ISO 639-1 language code } ``` **When `text=false`:** ```typescript { "content": [ { "text": string, // Transcript segment "offset": number, // Start time in milliseconds "duration": number, // Duration in milliseconds "lang": string // ISO 639-1 language code of chunk } ], "lang": string // ISO 639-1 language code of transcript } ``` ### Latency Due to the duration of transcript translation tasks, the endpoint may take 20 or more seconds to complete. Please make sure to increase the request timeout in your application. ### Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. ### Supported YouTube URL Formats `url` parameter supports various YouTube URL formats. See this [page](/youtube/supported-url-formats) for more details. ## Pricing * 1 minute of transcript = 30 credits # Playlist Source: https://docs.supadata.ai/youtube/playlist Use this API endpoint to fetch metadata from a YouTube playlist including title, description, video count, and more. ## Quick Start ### Request ```js Node import { Supadata, YoutubeChannel } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); const channel: YoutubeChannel = await supadata.youtube.channel({ id: 'https://youtube.com/@RickAstleyVEVO', // can be url, channel id, handle }); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") channel = supadata.youtube.channel(id="https://youtube.com/@RickAstleyVEVO") # can be url, channel id, handle print(f"Channel: {channel}") ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/youtube/playlist?id=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' \ -H 'x-api-key: YOUR_API_KEY' ``` ### Response ```json { "id": "PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", "title": "My Favorite Videos", "description": "A collection of my favorite videos", "videoCount": 25, "viewCount": 1000000, "lastUpdated": "2023-01-01T00:00:00.000Z", "channel": { "id": "UCuAXFkgsw1L7xaCfnd5JJOw", "name": "Rick Astley" } } ``` ## Specification ### Endpoint `GET https://api.supadata.ai/v1/youtube/playlist` Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key). ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------------------------------------------------------ | | id | string | Yes | YouTube playlist URL or ID. See [Supported YouTube URL Formats](/youtube/supported-url-formats). | ## Playlist Videos You can also retrieve a list of video IDs from a playlist using the [Playlist Videos](/youtube/playlist-videos) endpoint. ### Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. ### Supported YouTube Identifiers The universal `id` parameter supports various YouTube URL and ID formats. See this [page](/youtube/supported-url-formats) for more details. ## Pricing * 1 playlist metadata request = 1 credit # Playlist Videos Source: https://docs.supadata.ai/youtube/playlist-videos Use this API endpoint to fetch a list of video IDs from a YouTube playlist. ## Quick Start ### Request ```js Node import { Supadata, VideoIds } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); const playlistVideos: VideoIds = await supadata.youtube.playlist.videos({ id: 'https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc', // can be url or playlist id limit: 10, }); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") playlist_videos = supadata.youtube.playlist.videos( id="https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc", # can be url or playlist id limit=50 ) print(f"Regular videos: {playlist_videos.video_ids}") print(f"Shorts: {playlist_videos.short_ids}") print(f"Live: {playlist_videos.live_ids}") ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/youtube/playlist/videos?id=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc&limit=20' \ -H 'x-api-key: YOUR_API_KEY' ``` ### Response ```json { "videoIds": ["dQw4w9WgXcQ", "xvFZjo5PgG0"], "shortIds": ["xvFZjo5PgG0", "dQw4w9WgXcQ"], "liveIds": ["dQw4w9WgXcQ", "xvFZjo5PgG0"] } ``` ## Specification ### Endpoint `GET https://api.supadata.ai/v1/youtube/playlist/videos` Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key). ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------------------------------------------------------ | | id | string | Yes | YouTube playlist URL or ID. See [Supported YouTube URL Formats](/youtube/supported-url-formats). | | limit | number | No | Maximum number of video IDs to return. Default: 100. Max: 5000 | ### Response Format ```typescript { "videoIds": string[], // List of vertical YouTube video IDs "shortIds": string[], // List of Shorts IDs "liveIds": string[] // List of live video IDs } ``` ### Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. ### Supported YouTube Identifiers The universal `id` parameter supports various YouTube URL and ID formats. See this [page](/youtube/supported-url-formats) for more details. ## Working with Playlist Videos After retrieving the list of video IDs, you can: 1. Get metadata for each video using the [Video Metadata](/youtube/video) endpoint 2. Get transcripts for each video using the [Transcript](/get-transcript) endpoint For large playlists, consider using the `limit` parameter to control the number of results returned. ## Pricing * 1 playlist videos request = 1 credit # Languages Source: https://docs.supadata.ai/youtube/supported-language-codes Supported languages for YouTube transcripts. ## Supported YouTube languages The `lang` parameter value designates the desired language for video transcripts. By specifying a particular language code in the Transcript API requests, you can indicate your preference for the language of the transcript. If the preferred language is not available yet, a default language will be used. You can use a [dedicated endpoint](/youtube/get-transcript-translation) to perform translation. The following values are valid for the `lang` search parameter: | Language Code | Language Name | | ------------- | ------------------------ | | af | Afrikaans | | ak | Akan | | sq | Albanian | | am | Amharic | | ar | Arabic | | hy | Armenian | | as | Assamese | | ay | Aymara | | az | Azerbaijani | | bn | Bangla | | eu | Basque | | be | Belarusian | | bho | Bhojpuri | | bs | Bosnian | | bg | Bulgarian | | my | Burmese | | ca | Catalan | | ceb | Cebuano | | zh | Chinese | | zh-HK | Chinese (Hong Kong) | | zh-CN | Chinese (China) | | zh-SG | Chinese (Singapore) | | zh-TW | Chinese (Taiwan) | | zh-Hans | Chinese (Simplified) | | zh-Hant | Chinese (Traditional) | | hak-TW | Hakka Chinese (Taiwan) | | nan-TW | Min Nan Chinese (Taiwan) | | co | Corsican | | hr | Croatian | | cs | Czech | | da | Danish | | dv | Divehi | | nl | Dutch | | en | English | | en-US | English (United States) | | eo | Esperanto | | et | Estonian | | ee | Ewe | | fil | Filipino | | fi | Finnish | | fr | French | | gl | Galician | | lg | Ganda | | ka | Georgian | | de | German | | el | Greek | | gn | Guarani | | gu | Gujarati | | ht | Haitian Creole | | ha | Hausa | | haw | Hawaiian | | iw | Hebrew | | hi | Hindi | | hmn | Hmong | | hu | Hungarian | | is | Icelandic | | ig | Igbo | | id | Indonesian | | ga | Irish | | it | Italian | | ja | Japanese | | jv | Javanese | | kn | Kannada | | kk | Kazakh | | km | Khmer | | rw | Kinyarwanda | | ko | Korean | | kri | Krio | | ku | Kurdish | | ky | Kyrgyz | | lo | Lao | | la | Latin | | lv | Latvian | | ln | Lingala | | lt | Lithuanian | | lb | Luxembourgish | | mk | Macedonian | | mg | Malagasy | | ms | Malay | | ml | Malayalam | | mt | Maltese | | mi | Māori | | mr | Marathi | | mn | Mongolian | | ne | Nepali | | nso | Northern Sotho | | no | Norwegian | | ny | Nyanja | | or | Odia | | om | Oromo | | ps | Pashto | | fa | Persian | | pl | Polish | | pt | Portuguese | | pa | Punjabi | | qu | Quechua | | ro | Romanian | | ru | Russian | | sm | Samoan | | sa | Sanskrit | | gd | Scottish Gaelic | | sr | Serbian | | sn | Shona | | sd | Sindhi | | si | Sinhala | | sk | Slovak | | sl | Slovenian | | so | Somali | | st | Southern Sotho | | es | Spanish | | su | Sundanese | | sw | Swahili | | sv | Swedish | | tg | Tajik | | ta | Tamil | | tt | Tatar | | te | Telugu | | th | Thai | | ti | Tigrinya | | ts | Tsonga | | tr | Turkish | | tk | Turkmen | | uk | Ukrainian | | ur | Urdu | | ug | Uyghur | | uz | Uzbek | | vi | Vietnamese | | cy | Welsh | | fy | Western Frisian | | xh | Xhosa | | yi | Yiddish | | yo | Yoruba | | zu | Zulu | # URL Formats Source: https://docs.supadata.ai/youtube/supported-url-formats Supported YouTube URL formats for videos, playlists, and channels. ## Supported YouTube URL Formats The API supports various input formats for referencing videos, playlists and channels. Here are the supported formats: | Content Type | Supported Formats | Example | | ------------ | ----------------- | ---------------------------------------------------------------------- | | Videos | YouTube video URL | `https://youtube.com/watch?v=dQw4w9WgXcQ` | | | Short URL | `http://youtu.be/dQw4w9WgXcQ` | | | Shorts URL | `https://youtube.com/shorts/dQw4w9WgXcQ` | | | Embed URL | `http://www.youtube.com/embed/dQw4w9WgXcQ` | | | Video ID | `dQw4w9WgXcQ` | | Playlists | Playlist URL | `https://youtube.com/playlist?list=PL9tY0BWXOZFuFEG_GtOBZ8-8wbkH-NVAr` | | | Playlist ID | `PL9tY0BWXOZFuFEG_GtOBZ8-8wbkH-NVAr` | | Channels | Channel URL | `https://youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw` | | | Custom URL | `https://youtube.com/c/RickAstley` | | | Handle URL | `https://youtube.com/@RickAstley` | | | Channel ID | `UCuAXFkgsw1L7xaCfnd5JJOw` | ### Not supported content types: * Live stream videos - not possible to fetch transcripts of currently streamed videos * Private videos - will return a 404 error * User profile links # Video Metadata Source: https://docs.supadata.ai/youtube/video Use this API endpoint to fetch metadata from a YouTube video including title, description, channel info, and more. ## Quick Start ### Request ```js Node import { Supadata, YoutubeVideo } from '@supadata/js'; // Initialize the client const supadata = new Supadata({ apiKey: 'YOUR_API_KEY', }); const video: YoutubeVideo = await supadata.youtube.video({ id: 'dQw4w9WgXcQ', // can be url or video id }); ``` ```python Python from supadata import Supadata, SupadataError # Initialize the client supadata = Supadata(api_key="YOUR_API_KEY") video = supadata.youtube.video(id="https://youtu.be/dQw4w9WgXcQ") # can be url or video id print(f"Video: {video}") ``` ```bash cURL curl -X GET 'https://api.supadata.ai/v1/youtube/video?id=dQw4w9WgXcQ' \ -H 'x-api-key: YOUR_API_KEY' ``` ### Response ```json { "id": "dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)", "description": "The official music video for \"Never Gonna Give You Up\"...", "duration": 213, "channel": { "id": "UCuAXFkgsw1L7xaCfnd5JJOw", "name": "Rick Astley" }, "tags": ["Rick Astley", "Official Video", "Music"], "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "uploadDate": "2009-10-25T00:00:00.000Z", "viewCount": 1234567890, "likeCount": 12345678, "transcriptLanguages": ["en", "es", "fr"] } ``` ## Specification ### Endpoint `GET https://api.supadata.ai/v1/youtube/video` Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key). ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------------------------------------------------------- | | id | string | Yes | YouTube video URL or ID. See [Supported YouTube URL Formats](/youtube/supported-url-formats). | ### Error Codes The API returns HTTP status codes and error codes. See this [page](/errors) for more details. ### Supported YouTube Identifiers The universal `id` parameter supports various YouTube URL and ID formats. See this [page](/youtube/supported-url-formats) for more details. ## Pricing * 1 video metadata request = 1 credit