# Get Account Information
Source: https://docs.supadata.ai/api-reference/endpoint/account/me
v1-openapi GET /me
Retrieve organization details, plan information, and credit usage.
# Extract
Source: https://docs.supadata.ai/api-reference/endpoint/extract/extract
v1-openapi POST /extract
Use AI to analyze video content and extract structured data. Provide either a prompt describing what to extract, a JSON Schema for the output format, or both. Supports YouTube, TikTok, Instagram, Twitter/X, and Facebook videos. Returns a job ID for asynchronous processing. Use the `/extract/:jobId` endpoint to poll for results.
# Extract Result
Source: https://docs.supadata.ai/api-reference/endpoint/extract/extract-get
v1-openapi GET /extract/{jobId}
Get results for an extract job by job ID.
# Metadata
Source: https://docs.supadata.ai/api-reference/endpoint/metadata/metadata
v1-openapi GET /metadata
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.
# Transcript
Source: https://docs.supadata.ai/api-reference/endpoint/transcript/transcript
v1-openapi GET /transcript
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.
# 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 by job ID.
# 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.
# Search
Source: https://docs.supadata.ai/api-reference/endpoint/youtube/search
v1-openapi GET /youtube/search
Search YouTube for videos, channels, and playlists with advanced filters.
# 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 social media or file transcript.
Get social media post metadata.
Extract structured data from videos using AI.
Extract content from any website in markdown format.
## Base URL
All requests contain the following base URL:
```sh theme={null}
https://api.supadata.ai/v1
```
## Authentication
For authentication, it's required to include a `x-api-key` header.
```sh theme={null}
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.
# Community Resources
Source: https://docs.supadata.ai/community-resources
Explore tutorials, guides, and videos about using Supadata
## YouTube Videos
Browse our collection of community-created videos and tutorials organized by platform.
### Coding
### n8n Integration
### Make Integration
### Zapier Integration
### Other Resources
# 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 theme={null}
{
"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 [Supadata status page](https://status.supadata.ai) 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 theme={null}
{
"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 theme={null}
{
"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](https://dash.supadata.ai/organizations/settings/organization/billing) 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 |
| [Forbidden](/errors/forbidden) | Access to this resource is forbidden | 403 |
| [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 theme={null}
{
"error": "error-code",
"message": "Human readable error message",
"details": "Detailed explanation of the error",
"documentationUrl": "https://docs.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 theme={null}
{
"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 theme={null}
{
"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 theme={null}
{
"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](https://dash.supadata.ai)
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 theme={null}
{
"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.
# Extract
Source: https://docs.supadata.ai/get-extract
Use this API endpoint to extract structured data from videos hosted on YouTube, TikTok, Instagram, X (Twitter), Facebook or a public file URL. Supadata uses AI to analyze the video and return data matching your prompt or schema.
![]()
## Quick Start
### Request
```javascript Node.js theme={null} theme={null} theme={null} theme={null} theme={null}
import { Supadata } from '@supadata/js';
const supadata = new Supadata({
apiKey: 'YOUR_API_KEY',
});
// Start extract job
const job = await supadata.extract({
url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
prompt: 'How many times does a dog appear in this video? Describe each appearance.',
});
console.log(job.jobId);
```
```python Python theme={null} theme={null} theme={null} theme={null} theme={null}
from supadata import Supadata
supadata = Supadata(api_key="YOUR_API_KEY")
# Start extract job
job = supadata.extract(
url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
prompt="How many times does a dog appear in this video? Describe each appearance."
)
print(job.job_id)
```
```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null}
curl -X POST "https://api.supadata.ai/v1/extract" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"prompt": "How many times does a dog appear in this video? Describe each appearance."
}'
```
### Response (HTTP 202)
```json theme={null}
{
"jobId": "123e4567-e89b-12d3-a456-426614174000"
}
```
The extract endpoint always returns a job ID for asynchronous processing. Use the job ID to [poll for results](#getting-job-results).
### Job Result
```json theme={null}
{
"status": "completed",
"data": {
"totalAppearances": 3,
"appearances": [
{ "timestamp": "0:12", "description": "Golden retriever runs across the park" },
{ "timestamp": "1:45", "description": "Same dog catches a frisbee mid-air" },
{ "timestamp": "3:20", "description": "Dog rolls over on the grass for belly rubs" }
]
},
"schema": {
"type": "object",
"properties": {
"totalAppearances": {
"type": "number"
},
"appearances": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": { "type": "string" },
"description": { "type": "string" }
},
"required": ["timestamp", "description"]
}
}
},
"required": ["totalAppearances", "appearances"]
}
}
```
## Specification
### Endpoint
`POST https://api.supadata.ai/v1/extract`
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).
### Request Body
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| url | string | Yes | URL of the video to extract data from. Must be either YouTube, TikTok, Instagram, X (Twitter), Facebook or a public file URL. |
| prompt | string | No | Description of what data to extract from the video. Required if `schema` is not provided. |
| schema | object | No | JSON Schema defining the structure of data to extract. Required if `prompt` is not provided. |
At least one of `prompt` or `schema` must be provided. You can also provide both for maximum control over the output.
The `/extract` endpoint uses AI to **analyze video content** (what is seen and heard in the video). It does not retrieve transcripts, titles, descriptions, or platform metrics. For those, use the dedicated [Transcript](/get-transcript) or [Metadata](/get-metadata) endpoints.
### Schema
The `schema` parameter accepts a [JSON Schema](https://json-schema.org/) object that defines the expected structure of the extracted data. This is useful for building pipelines that need consistent, predictable output formats.
#### How it works
* **Prompt only**: When only `prompt` is provided, the AI automatically generates a JSON Schema based on the prompt. The generated schema is returned in the `schema` field of the response, so you can reuse it for future requests to get consistent outputs.
With prompt-only mode, the response structure (key names, nesting, and types) may vary between calls since the AI generates the schema dynamically. To ensure a consistent output format across requests, provide an explicit `schema`.
* **Schema only**: When only `schema` is provided, the AI extracts data structured exactly according to the schema.
* **Both prompt and schema**: The schema defines the output structure, while the prompt guides what content to extract. This gives you maximum control over the extraction.
#### Example with schema
```json theme={null}
{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"schema": {
"type": "object",
"properties": {
"totalAppearances": {
"type": "number",
"description": "Total number of times a dog appears"
},
"appearances": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": { "type": "string", "description": "Timestamp of the appearance" },
"description": { "type": "string", "description": "What the dog is doing" }
},
"required": ["timestamp", "description"]
},
"description": "Each individual dog appearance"
}
},
"required": ["totalAppearances", "appearances"]
}
}
```
Start with just a `prompt` to let the AI generate a schema, then reuse the returned `schema` in subsequent requests for consistent outputs across multiple videos.
#### Schema Examples
Copy any of these schemas and use them directly in your requests.
Extract cooking recipes with ingredients, steps and nutritional info.
```json theme={null}
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Name of the dish"
},
"servings": {
"type": "number",
"description": "Number of servings"
},
"prepTimeMinutes": {
"type": "number",
"description": "Preparation time in minutes"
},
"cookTimeMinutes": {
"type": "number",
"description": "Cooking time in minutes"
},
"ingredients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"quantity": { "type": "string" }
},
"required": ["name", "quantity"]
},
"description": "List of ingredients with quantities"
},
"steps": {
"type": "array",
"items": { "type": "string" },
"description": "Step-by-step cooking instructions"
}
},
"required": ["title", "ingredients", "steps"]
}
```
Extract timestamped chapters and sections from a video.
```json theme={null}
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Video title"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Chapter title"
},
"startTime": {
"type": "string",
"description": "Start timestamp (e.g. 0:00, 2:35, 1:02:15)"
},
"summary": {
"type": "string",
"description": "Brief summary of what is covered"
}
},
"required": ["title", "startTime", "summary"]
},
"description": "Ordered list of video chapters"
}
},
"required": ["title", "chapters"]
}
```
Extract main points, takeaways and action items from educational or business content.
```json theme={null}
{
"type": "object",
"properties": {
"topic": {
"type": "string",
"description": "Main topic of the video"
},
"summary": {
"type": "string",
"description": "One-paragraph summary"
},
"keyTakeaways": {
"type": "array",
"items": { "type": "string" },
"description": "Main points and insights"
},
"actionItems": {
"type": "array",
"items": { "type": "string" },
"description": "Concrete action items or next steps"
}
},
"required": ["topic", "summary", "keyTakeaways"]
}
```
Extract workout routines with exercises, sets, reps and rest periods.
```json theme={null}
{
"type": "object",
"properties": {
"routineName": {
"type": "string",
"description": "Name of the workout routine"
},
"difficulty": {
"type": "string",
"enum": ["beginner", "intermediate", "advanced"],
"description": "Difficulty level"
},
"durationMinutes": {
"type": "number",
"description": "Total workout duration in minutes"
},
"equipment": {
"type": "array",
"items": { "type": "string" },
"description": "Required equipment"
},
"exercises": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"sets": { "type": "number" },
"reps": { "type": "string", "description": "Reps or duration (e.g. '12' or '30 seconds')" },
"restSeconds": { "type": "number" }
},
"required": ["name"]
},
"description": "Ordered list of exercises"
}
},
"required": ["routineName", "exercises"]
}
```
Extract step-by-step repair or DIY instructions from tutorial videos.
```json theme={null}
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "What is being repaired or built"
},
"difficultyLevel": {
"type": "string",
"enum": ["easy", "moderate", "hard"],
"description": "Difficulty level"
},
"estimatedTimeMinutes": {
"type": "number",
"description": "Estimated time to complete"
},
"toolsRequired": {
"type": "array",
"items": { "type": "string" },
"description": "Tools needed"
},
"partsRequired": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"quantity": { "type": "number" }
},
"required": ["name"]
},
"description": "Parts or materials needed"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"step": { "type": "number" },
"instruction": { "type": "string" },
"warning": { "type": "string", "description": "Safety warning if applicable" }
},
"required": ["step", "instruction"]
},
"description": "Step-by-step instructions"
}
},
"required": ["title", "steps"]
}
```
Extract practical tips and life hacks from advice videos.
```json theme={null}
{
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "Category of tips (e.g. productivity, cooking, cleaning)"
},
"tips": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Short title for the tip"
},
"description": {
"type": "string",
"description": "Detailed explanation of the tip"
},
"materialsNeeded": {
"type": "array",
"items": { "type": "string" },
"description": "Materials or items needed, if any"
}
},
"required": ["title", "description"]
},
"description": "List of tips or hacks"
}
},
"required": ["tips"]
}
```
Extract structured product review data from review videos.
```json theme={null}
{
"type": "object",
"properties": {
"productName": {
"type": "string",
"description": "Name of the product being reviewed"
},
"brand": {
"type": "string",
"description": "Brand or manufacturer"
},
"rating": {
"type": "number",
"description": "Overall rating out of 10"
},
"pros": {
"type": "array",
"items": { "type": "string" },
"description": "Positive aspects"
},
"cons": {
"type": "array",
"items": { "type": "string" },
"description": "Negative aspects"
},
"verdict": {
"type": "string",
"description": "Final verdict or recommendation"
}
},
"required": ["productName", "pros", "cons", "verdict"]
}
```
### Response Format
The API always returns HTTP 202 with a job ID for asynchronous processing.
```typescript theme={null}
{
"jobId": string // Job ID for checking results
}
```
### Getting Job Results
Poll for results using the job ID endpoint:
```javascript Node.js theme={null}
// Get job results
const result = await supadata.extract.getResults(job.jobId);
if (result.status === "completed") {
console.log(result.data);
} else if (result.status === "failed") {
console.error(result.error);
} else {
console.log("Job status:", result.status);
}
```
```python Python theme={null}
# Get job results
result = supadata.extract.get_results(job.job_id)
if result.status == "completed":
print(result.data)
elif result.status == "failed":
print(result.error)
else:
print(f"Job status: {result.status}")
```
```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null}
curl -X GET "https://api.supadata.ai/v1/extract/123e4567-e89b-12d3-a456-426614174000" \
-H "x-api-key: YOUR_API_KEY"
```
#### Response
```json theme={null}
{
"status": "completed",
"data": {
"totalAppearances": 3,
"appearances": [
{ "timestamp": "0:12", "description": "Golden retriever runs across the park" },
{ "timestamp": "1:45", "description": "Same dog catches a frisbee mid-air" },
{ "timestamp": "3:20", "description": "Dog rolls over on the grass for belly rubs" }
]
},
"schema": {
"type": "object",
"properties": {
"totalAppearances": {
"type": "number"
},
"appearances": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": { "type": "string" },
"description": { "type": "string" }
},
"required": ["timestamp", "description"]
}
}
},
"required": ["totalAppearances", "appearances"]
}
}
```
| Field | Type | Description |
| ------ | ------ | -------------------------------------------------------------------------------------------------- |
| status | string | Job status: `queued`, `active`, `completed`, or `failed` |
| data | object | Extracted data structured according to the schema. Only present when status is `completed`. |
| schema | object | JSON Schema used for extraction. Only present when no schema was provided in the original request. |
| error | object | Error details. Only present when status is `failed`. |
#### 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 `data` field will contain the extracted data when status is
"completed", or the `error` field will contain error details when status is
"failed".
#### Polling Guidelines
* **Polling interval**: We recommend polling every 1 second
* **Job expiry**: Job results are available for **1 hour** after completion. After that, the endpoint will return a `404 Not Found` error. Make sure to retrieve and store results promptly after the job completes.
### 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/`
* Facebook video URL, e.g.`https://www.facebook.com/reel/682865820350105/`
* Publicly accessible file URL, e.g. `https://bucket.s3.eu-north-1.amazonaws.com/file.mp4`
### Video Accessibility
Only publicly accessible videos can be processed. Videos that require authentication or have restricted access will return errors:
* **Login-required videos** - Videos that require signing in
* **Membership/subscriber-only videos** - Content behind paywalls
* **Private videos** - Videos not publicly listed
* **Age-restricted videos** - Content with age verification requirements
* **Heavily geoblocked videos** - Videos available only in specific countries
To verify if a video is accessible, try opening it in a browser incognito/private window without signing in. If you can watch the video, it can be processed.
If the video is not accessible, the API will return:
* `404 Not Found` - Video does not exist or is private
* `403 Forbidden` - Video requires authentication or is restricted
### File Support
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 200 MB. Videos longer than 55 minutes are not supported.
## Latency
Extraction always involves AI processing and returns a job ID (HTTP 202) for asynchronous handling. Processing time is correlated with video duration - the longer the video, the longer the extraction takes.
Consider this latency when implementing time-outs and UX in your project. Always implement the asynchronous polling pattern to retrieve results.
## Pricing
* 1 extraction minute = 5 credits (minimum 5 credits per request)
No credits are charged for checking extraction job status.
# Metadata
Source: https://docs.supadata.ai/get-metadata
Use this API endpoint to fetch metadata from videos and posts hosted on YouTube, TikTok, Instagram, X (Twitter) or Facebook. Supadata returns a unified schema with platform-specific fields.
## Quick Start
### Request
```javascript Node.js theme={null}
import { Supadata } from '@supadata/js';
const supadata = new Supadata({
apiKey: 'YOUR_API_KEY',
});
const metadata = await supadata.metadata({
url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
});
console.log(metadata)
```
```python Python theme={null}
from supadata import Supadata
supadata = Supadata(api_key="YOUR_API_KEY")
metadata = supadata.metadata(
url="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
)
print(metadata)
```
```bash cURL theme={null}
curl -X GET "https://api.supadata.ai/v1/metadata?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json"
```
### Response
```json theme={null}
{
"platform": "youtube",
"type": "video",
"id": "dQw4w9WgXcQ",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"title": "Rick Astley - Never Gonna Give You Up",
"description": "The official video for \"Never Gonna Give You Up\"...",
"author": {
"displayName": "Rick Astley",
"avatarUrl": "https://yt3.ggpht.com/..."
},
"stats": {
"views": 1234567890,
"likes": 12345678,
"comments": 200000,
"shares": null
},
"media": {
"type": "video",
"duration": 213,
"thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
},
"tags": ["Rick Astley", "Never Gonna Give You Up", "Official Video"],
"createdAt": "2009-10-25T00:00:00Z",
"additionalData": {
"channelId": "UCuAXFkgsw1L7xaCfnd5JJOw"
}
}
```
## Specification
### Endpoint
`GET https://api.supadata.ai/v1/metadata`
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 media to get metadata from. Must be YouTube, TikTok, Instagram, X (Twitter) or Facebook. It is recommended to encode the URL before sending it as a query parameter. |
### Response Format
The API returns a unified metadata schema with platform-specific fields.
```typescript theme={null}
{
"platform": "youtube" | "tiktok" | "instagram" | "twitter" | "facebook",
"type": "video" | "image" | "carousel" | "post",
"id": string,
"url": string,
"title": string | null,
"description": string | null,
"author": {
"username": string,
"displayName": string,
"avatarUrl": string,
"verified": boolean
},
"stats": {
"views": number | null,
"likes": number | null,
"comments": number | null,
"shares": number | null
},
"media": VideoMedia | ImageMedia | CarouselMedia | PostMedia,
"tags": string[],
"createdAt": string,
"additionalData": object // Platform-specific fields
}
```
### Error Codes
The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
### Supported URL Formats
The metadata endpoint supports various media URLs, eg:
**YouTube:**
* `https://www.youtube.com/watch?v=dQw4w9WgXcQ`
* `https://youtu.be/dQw4w9WgXcQ`
* `https://www.youtube.com/embed/dQw4w9WgXcQ`
* `https://www.youtube.com/shorts/dQw4w9WgXcQ`
* `https://www.youtube.com/live/dQw4w9WgXcQ`
**TikTok:**
* `https://www.tiktok.com/@username/video/7234567890123456789`
* `https://vm.tiktok.com/AAAAZZZZZ`
* `https://m.tiktok.com/v/7234567890123456789`
**Instagram:**
* `https://www.instagram.com/reel/C1234567890`
* `https://www.instagram.com/p/C1234567890`
* `https://www.instagram.com/tv/C1234567890`
**Twitter/X:**
* `https://twitter.com/username/status/1234567890123456789`
* `https://x.com/username/status/1234567890123456789`
**Facebook**
* `https://www.facebook.com/reel/682865820350105/`
* `https://www.facebook.com/groups/123456789012345/permalink/987654321098765/`
* `https://m.facebook.com/examplepage/posts/123123123123123/`
* `https://www.facebook.com/share/p/123123123123123/`
* Marketplace & Event URLs are not supported yet.
## Base Schema
All metadata responses share a common base schema regardless of platform. Here are the important details:
* **type**: Acts as a discriminator that determines the structure of the `media` field (see [Media Types](#media-types) below)
* **title** and **description**: May be `null` for some platforms or content types
* **stats**: `null` values indicate the metric is unavailable or not applicable for the platform.
* **createdAt**: ISO 8601 formatted timestamp
* **additionalData**: Contains platform-specific fields not included in the base schema
## Media Types
The `media` field structure varies based on the `type` discriminator:
* Video: `duration`, `thumbnailUrl`
* Image: `url`
* Carousel: `items` (array of video/image objects)
* Post: no additional fields
## Platform-Specific Fields
Different platforms and media types may include additional fields in the `additionalData` object, for example:
* Channel information for YouTube
* Music/sound information for TikTok
* Retweet/quote information for X (Twitter)
Platform-specific fields in `additionalData` may vary and are subject to
change based on platform API availability.
## Pricing
All metadata requests cost **1 credit**, regardless of platform or media type.
# 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), Facebook or a public file URL. Supadata will fetch existing transcript or fall back to AI to create one.
## Quick Start
### Request
```js Node theme={null}
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 theme={null}
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 theme={null}
curl -X GET 'https://api.supadata.ai/v1/transcript?url=https://youtu.be/dQw4w9WgXcQ' \
-H 'x-api-key: YOUR_API_KEY'
```
### Response
```json theme={null}
{
"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), Facebook 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`. See Pricing for details.
### 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 theme={null}
{
"content": string,
"lang": string // ISO 639-1 language code
"availableLangs": string[] // List of available languages
}
```
When `text=false`:
```typescript theme={null}
{
"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 theme={null}
{
"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 theme={null}
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 theme={null}
# 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 theme={null}
curl -X GET 'https://api.supadata.ai/v1/transcript/123e4567-e89b-12d3-a456-426614174000' \
-H 'x-api-key: YOUR_API_KEY'
```
#### Response
```json theme={null}
{
"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".
#### Polling Guidelines
* **Polling interval**: We recommend polling every 1 second
* **Job expiry**: Job results are available for **1 hour** after completion. After that, the endpoint will return a `404 Not Found` error. Make sure to retrieve and store results promptly after the job completes.
### 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/`
* Facebook video URL, e.g.`https://www.facebook.com/reel/682865820350105/`
* Publicly accessible file URL, e.g. `https://bucket.s3.eu-north-1.amazonaws.com/file.mp4`
### Video Accessibility
Only publicly accessible videos can be transcribed. Videos that require authentication or have restricted access will return errors:
* **Login-required videos** - Videos that require signing in
* **Membership/subscriber-only videos** - Content behind paywalls
* **Private videos** - Videos not publicly listed
* **Age-restricted videos** - Content with age verification requirements
* **Heavily geoblocked videos** - Videos available only in specific countries
To verify if a video is accessible, try opening it in a browser incognito/private window without signing in. If you can watch the video, it can be transcribed.
If the video is not accessible, the API will return:
* `404 Not Found` - Video does not exist or is private
* `403 Forbidden` - Video requires authentication or is restricted
### 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.
## Latency
Requests for existing transcripts (eg. in `mode=native`) are resolved at normal latency. Requests that involve AI generation (eg. in `mode=generate`) can take up to 60s if they do not return an asynchronous job ID earlier.
### AI Transcription Time
AI transcription time is correlated with video duration - the longer the video, the longer the transcription takes. Videos longer than 20 minutes will automatically trigger an asynchronous job, returning a job ID (HTTP 202) instead of the transcript directly.
Consider this latency when implementing time-outs and UX in your project. For example, if your app times out before receiving a response, the request will still count towards your credit usage.
## Pricing
* 1 native transcript = 1 credit
* 1 generated transcript minute = 2 credits
No credits are charged for checking transcription job status. 1 credit is charged when request to get a transcript returns status 206 (Transcript Unavailable).
### Examples
| Case | Mode | What happens | Credits consumed |
| ---------------------------------------- | ---------- | -------------------------------------- | ------------------------------ |
| YouTube video without any transcript | `auto` | Supadata generates transcript with AI | 2 per min of video |
| Instagram video | `native` | No transcript available response (206) | 1 |
| Instagram video with existing transcript | `auto` | Supadata returns existing transcript | 1 |
| TikTok video | `generate` | Supadata generates transcript with AI | 2 per min of video (usually 2) |
### Tracking Credit Usage
There are two ways to check how many credits were consumed in a request:
1. **Dashboard**: The [dashboard](https://dash.supadata.ai) has a history section showing all API requests and the number of credits used for each.
2. **Response header**: Each API response includes an `x-billable-requests` header containing the number of credits consumed by that request.
# Introduction
Source: https://docs.supadata.ai/index
Welcome to the Supadata documentation. Our API provides powerful tools for extracting web content.
## Overview
Supadata offers four main services:
* Video Transcripts - Extract transcripts from YouTube, TikTok, Instagram, Facebook, X (Twitter) and video files
* Media Metadata - Get social media post data like title, author and engagement metrics
* Structured Data Extraction - Use AI to extract structured data from videos across all supported platforms
* 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)
* [n8n](/integrations/n8n)
* [Make](/integrations/make)
* [Zapier](/integrations/zapier)
* [Active Pieces](/integrations/activepieces)
* [MCP](/integrations/mcp)
## 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 theme={null}
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.
# Community Resources
The Supadata community has created various resources and guides for using Supadata. [You can find them here](/community-resources).
# Active Pieces
Source: https://docs.supadata.ai/integrations/activepieces
Open-source no-code automation with Supadata integration
## Quick Start
## Installation
The Supadata integration is available as a piece in Active Pieces. To install:
1. Get your API key from [Supadata Dashboard](https://dash.supadata.ai)
2. Open your Active Pieces dashboard
3. Navigate to **Pieces** and search for "Supadata"
4. Click **Install**
5. Add Supadata API key in Active Pieces connections
## Resources
* [Active Pieces Website](https://activepieces.com)
* [Active Pieces Documentation](https://docs.activepieces.com)
* [Active Pieces Community](https://community.activepieces.com)
# Make
Source: https://docs.supadata.ai/integrations/make
Build powerful visual automation workflows with Supadata and Make (formerly Integromat)
## Quick Start
## Installation
The Supadata integration is available as a module in Make. To install:
1. Get your API key from [Supadata Dashboard](https://dash.supadata.ai)
2. Open your Make dashboard
3. Create a new scenario and search for "Supadata"
4. Click **Install**
5. Add Supadata API key when creating a connection
## Resources
* [Make Website](https://make.com)
* [Make Documentation](https://docs.make.com)
* [Make Community](https://community.make.com)
### Community Videos
# MCP
Source: https://docs.supadata.ai/integrations/mcp
Model Context Protocol server for AI-powered web and video scraping
## Overview
The Supadata MCP (Model Context Protocol) server enables powerful web and video scraping capabilities directly within AI development environments like Cursor, Claude Desktop, and VS Code. This open-source integration allows AI models to extract transcripts, scrape web pages, and crawl entire websites to gather context.
## Features
* **Multi-Platform Support**: Works with YouTube, TikTok, Instagram, Twitter, and more
* **AI-First Design**: Optimized for use with LLMs and AI assistants
* **Multiple Tools**: Transcript extraction, web scraping, site mapping, and crawling
* **Easy Integration**: Simple setup with popular AI tools
## Installation
### Manual Installation
```bash theme={null}
env X_API_KEY=your-api-key npx -y @supadata/mcp
```
## Integration Setup
### Claude / Claude Desktop / Cowork
Connect directly from Claude without manually configuring an API key.
1. Go to **Settings** → **Connectors**
2. Click **Add custom connector** and enter `Supadata` as the name and `https://api.supadata.ai/mcp` as the URL. Click **Add**.
![]()
3. Click **Authorize** when prompted to grant MCP access.
![]()
### Claude Code
1. Add the Supadata MCP server:
```bash theme={null}
claude mcp add --transport http supadata https://api.supadata.ai/mcp
```
2. Run `/mcp` in Claude Code and select **Authenticate** for Supadata to complete the OAuth flow in your browser.
### ChatGPT
1. Go to **Settings** → **Apps & Connectors**
2. Click **Create** to add a new connector
3. Enter `Supadata` as the name and `https://api.supadata.ai/mcp` as the connector URL
4. Click **Save**
To use it in a conversation, click the **+** icon in the composer, select **More** → **Developer mode**, and choose the Supadata connector.
### Cursor
1. Open Cursor Settings
2. Navigate to **MCPs & Integrations** → **New MCP Server**
3. Add new MCP server:
```json theme={null}
{
"supadata": {
"command": "npx",
"args": ["-y", "@supadata/mcp"],
"env": {
"X_API_KEY": "your-api-key"
}
}
}
```
### Windsurf
Add to `~/.windsurf/cascade/config.json`:
```json theme={null}
{
"mcpServers": {
"supadata": {
"command": "npx",
"args": ["-y", "@supadata/mcp"],
"env": {
"X_API_KEY": "your-api-key"
}
}
}
}
```
### VS Code
Using the MCP extension:
1. Install the MCP extension
2. Add Supadata server configuration
3. Set your API key in environment settings
## Configuration
### Environment Variables
* `X_API_KEY`: Your Supadata API key (required)
## Support
* [GitHub Issues](https://github.com/supadata-ai/mcp/issues)
* [MCP Documentation](https://github.com/supadata-ai/mcp#readme)
# n8n
Source: https://docs.supadata.ai/integrations/n8n
Integrate Supadata with n8n for powerful open-source workflow automation.
## Quick Start
## Installation
The Supadata integration is available as a verified node in n8n. To install:
1. Get your API key from [Supadata Dashboard](https://dash.supadata.ai)
2. Open your n8n dashboard
3. Open a workflow and search for "Supadata" when adding a node
4. Click **Install**
5. Add Supadata API key in n8n credentials
## Resources
* [n8n Website](https://n8n.io)
* [n8n Documentation](https://docs.n8n.io)
* [n8n Community Forum](https://community.n8n.io)
### Community Videos
# Node
Source: https://docs.supadata.ai/integrations/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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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/integrations/overview
Supadata SDKs and integrations help you easily extract data from websites using your preferred tools.
## Official SDKs
Explore the Python SDK for Supadata.
Explore the Node SDK for Supadata.
## Integrations
} href="n8n">
Open-source workflow automation tool with Supadata integration.
} href="zapier">
Connect Supadata with thousands of apps using automated workflows.
} href="make">
Visual automation platform for building complex workflows.
} href="activepieces">
Open-source no-code automation platform.
} href="mcp">
Model Context Protocol server for AI-powered scraping.
# Python
Source: https://docs.supadata.ai/integrations/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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
# 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 theme={null}
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 theme={null}
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}")
```
# Zapier
Source: https://docs.supadata.ai/integrations/zapier
Connect Supadata with 5,000+ apps using Zapier's automated workflows
## Quick Start
## Installation
The Supadata integration is available as an app in Zapier. To install:
1. Get your API key from [Supadata Dashboard](https://dash.supadata.ai)
2. Open your Zapier dashboard
3. Create a new Zap and search for "Supadata"
4. Select Supadata from the app list
5. Add Supadata API key when connecting your account
## Resources
* [Zapier Website](https://zapier.com)
* [Zapier Help Center](https://help.zapier.com)
* [Zapier Community](https://community.zapier.com)
### Community Videos
# 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{
"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 theme={null}
import { Supadata } from "@supadata/js";
const supadata = new Supadata("YOUR_API_KEY");
// Get crawl job results
// This automatically handles pagination and returns all pages
const crawlResult = await supadata.web.getCrawlResults(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("---");
});
} else if (crawlResult.status === "failed") {
console.error("Crawl job failed:", crawlResult.error);
} else {
console.log("Job status:", crawlResult.status);
}
```
```python Python theme={null}
from supadata import Supadata
supadata = Supadata("YOUR_API_KEY")
# Get crawl results
# This automatically handles pagination and returns all pages
crawl_result = supadata.web.get_crawl_results(job_id=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("---")
elif crawl_result.status == "failed":
print(f"Crawl job failed: {crawl_result.error}")
else:
print(f"Job status: {crawl_result.status}")
```
```bash cURL theme={null}
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 theme={null}
{
"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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{
"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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{
"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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{
"jobId": "123e4567-e89b-12d3-a456-426614174000"
}
```
### Video Metadata Batch
#### Request
```js Node theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{
"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 theme={null}
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 theme={null}
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 theme={null}
curl -X GET 'https://api.supadata.ai/v1/youtube/batch/123e4567-e89b-12d3-a456-426614174000' \
-H 'x-api-key: YOUR_API_KEY'
```
#### Response
```json theme={null}
{
"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 theme={null}
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 theme={null}
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 theme={null}
curl -X GET 'https://api.supadata.ai/v1/youtube/channel?id=RickAstleyVEVO' \
-H 'x-api-key: YOUR_API_KEY'
```
### Response
```json theme={null}
{
"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
"name": "Rick Astley",
"description": "The official Rick Astley YouTube channel",
"subscriberCount": 2000000,
"videoCount": 100,
"viewCount": 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 theme={null}
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 theme={null}
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 theme={null}
curl -X GET 'https://api.supadata.ai/v1/youtube/channel/videos?id=RickAstleyVEVO&limit=50' \
-H 'x-api-key: YOUR_API_KEY'
```
### Response
```json theme={null}
{
"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 theme={null}
{
"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
# 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{
"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 theme={null}
{
"content": string,
"lang": string // ISO 639-1 language code
}
```
**When `text=false`:**
```typescript theme={null}
{
"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 theme={null}
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 theme={null}
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 theme={null}
curl -X GET 'https://api.supadata.ai/v1/youtube/playlist?id=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc' \
-H 'x-api-key: YOUR_API_KEY'
```
### Response
```json theme={null}
{
"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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{
"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 theme={null}
{
"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
# Search
Source: https://docs.supadata.ai/youtube/search
Use this API endpoint to search YouTube for videos, channels, and playlists with advanced filtering options.
## Quick Start
### Request
```js Node theme={null}
import { Supadata } from "@supadata/js";
// Initialize the client
const supadata = new Supadata({
apiKey: "YOUR_API_KEY",
});
const searchResults = await supadata.youtube.search({
query: "never gonna give you up",
type: "video", // Optional: 'video', 'channel', 'playlist', 'all' (default 'all')
limit: 20, // Optional: get more than the first page of results
sortBy: "views", // Optional: 'relevance', 'rating', 'date', 'views'
uploadDate: "year", // Optional: 'hour', 'today', 'week', 'month', 'year'
duration: "medium", // Optional: 'short', 'medium', 'long',
features: ["hd", "subtitles"], // Optional
});
console.log(`Found ${searchResults.results.length} results`);
```
```python Python theme={null}
from supadata import Supadata
# Initialize the client
supadata = Supadata(api_key="YOUR_API_KEY")
search_results = supadata.youtube.search(
query="never gonna give you up",
type="video", # Optional: 'video', 'channel', 'playlist', 'all' (default 'all')
limit=20, # Optional: get more than the first page of results
sort_by="views", # Optional: 'relevance', 'rating', 'date', 'views'
upload_date="year", # Optional: 'hour', 'today', 'week', 'month', 'year'
duration="medium", # Optional: 'short', 'medium', 'long',
features=["hd", "subtitles"], # Optional
)
print(f"Found {len(search_results.results)} results")
for result in search_results.results:
print(f"{result.type}: {result.title}")
```
```bash cURL theme={null}
curl -X GET 'https://api.supadata.ai/v1/youtube/search?query=never%20gonna%20give%20you%20up&type=video&limit=20&sortBy=views&uploadDate=month' \
-H 'x-api-key: YOUR_API_KEY'
```
### Response
```json theme={null}
{
"query": "Rick Astley Never Gonna Give You Up",
"results": [
{
"type": "video",
"id": "dQw4w9WgXcQ",
"title": "Rick Astley - Never Gonna Give You Up (Official Video)",
"description": "The official music video for Rick Astley...",
"thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
"duration": 213,
"viewCount": 1234567890,
"uploadDate": "2009-10-25T00:00:00.000Z",
"channel": {
"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
"name": "Rick Astley",
"thumbnail": "https://yt3.ggpht.com/..."
}
},
{
"type": "channel",
"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
"title": "Rick Astley",
"description": "Official Rick Astley YouTube Channel...",
"thumbnail": "https://yt3.ggpht.com/...",
"subscriberCount": 2000000,
"videoCount": 100
},
{
"type": "playlist",
"id": "PLrAVp4ISIlVYYbGzAY_YX30NMdvOL_PGJ",
"title": "Best of Rick Astley",
"description": "A collection of Rick Astley's greatest hits",
"thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
"videoCount": 25,
"channel": {
"id": "UCuAXFkgsw1L7xaCfnd5JJOw",
"name": "Rick Astley"
}
}
],
"nextPageToken": "eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319"
}
```
## Specification
### Endpoint
`GET https://api.supadata.ai/v1/youtube/search`
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 |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| query | string | Yes | Search query string |
| type | string | No | Filter by content type. Options: `all` (default), `video`, `channel`, `playlist`, `movie` |
| uploadDate | string | No | Filter by upload date. Options: `all` (default), `hour`, `today`, `week`, `month`, `year` |
| duration | string | No | Filter by video duration. Options: `all` (default), `short` (\<4min), `medium` (4-20min), `long` (>20min) |
| sortBy | string | No | Sort order of results. Options: `relevance` (default), `rating`, `date`, `views` |
| features | array | No | Array of special features to filter by. Options: `hd`, `subtitles`, `creative-commons`, `3d`, `live`, `4k`, `360`, `location`, `hdr`, `vr180` |
| limit | number | No | Maximum number of results to return (1-5000). When provided, API automatically paginates to fetch up to this many results |
| nextPageToken | string | No | Token for fetching the next page of results. When provided, other filter parameters are ignored |
## Pagination
The search endpoint supports two different pagination modes depending on whether you use the `limit` parameter.
Supadata SDKs automatically handle pagination for you. Please use the API if
you need to control pagination.
### Automatic Pagination (with `limit`)
When you provide a `limit` parameter, the API automatically handles pagination for you:
```bash theme={null}
# Get up to 100 results automatically
curl -X GET 'https://api.supadata.ai/v1/youtube/search?query=programming&limit=100' \
-H 'x-api-key: YOUR_API_KEY'
```
**How it works:**
* The API fetches multiple pages behind the scenes until it reaches your desired `limit` or runs out of results
* You receive all results in a single response
* Each page fetched counts as 1 credit (so requesting 100 results might consume 5+ credits if each page contains \~20 results)
* No `nextPageToken` is returned since all requested results are included
**Use this when:**
* You need a specific number of results
* You want convenience over credit control
* You're building bulk data collection tools
### Manual Pagination (without `limit`)
When you don't provide a `limit` parameter, you get manual control over pagination:
```bash theme={null}
# Get first page
curl -X GET 'https://api.supadata.ai/v1/youtube/search?query=programming' \
-H 'x-api-key: YOUR_API_KEY'
# Get next page using the token from previous response
curl -X GET 'https://api.supadata.ai/v1/youtube/search?nextPageToken=TOKEN_HERE' \
-H 'x-api-key: YOUR_API_KEY'
```
**How it works:**
* You receive one page of results (\~20 items) per request
* Each request consumes exactly 1 credit
* A `nextPageToken` is included in the response for fetching additional pages
* When using `nextPageToken`, all other filter parameters are ignored
**Use this when:**
* You want precise credit control
* You're implementing infinite scroll or "Load More" functionality
* You only need the first page of results
* You're building interactive applications where users control pagination
### Error Codes
The API returns HTTP status codes and error codes. See this [page](/errors) for more details.
## Pricing
* 1 search request = 1 credit per page of results
* Using the `limit` parameter to fetch multiple pages automatically will consume credits for each page retrieved
# 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