Supadata

https://docs.supadata.ai
Admin
Supadata is an API platform for extracting video transcripts, social media metadata, web scraping,...
Tokens:108,767
Snippets:707
Trust Score:8.7
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Go Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Uses Go's net/http package to make a GET request to the endpoint. Requires an API key in the x-api-key header.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.supadata.ai/v1/youtube/video"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Ruby Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Uses Ruby's net/http library to make a GET request to the endpoint. Requires an API key in the x-api-key header.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.supadata.ai/v1/youtube/video")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Quick Start: Translate YouTube Transcript (Node, Python, cURL)

Source: https://docs.supadata.ai/youtube/get-transcript-translation

Quick Start request examples for the YouTube Transcript Translation endpoint. The Node example uses the @supadata/js client, the Python example uses the supadata package, and the cURL example calls the REST API directly. All require an API key and specify a videoId and lang (ISO 639-1).

```javascript
import {
  Supadata,
  TranslatedTranscript
} from '@supadata/js';

// Initialize the client
const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY',
});

const translated: TranslatedTranscript = await supadata.youtube.translate({
  videoId: 'dQw4w9WgXcQ',
  lang: 'es',
});

```

```python
from supadata import Supadata, SupadataError

# Initialize the client
supadata = Supadata(api_key="YOUR_API_KEY")

translated = supadata.youtube.translate(
    video_id="dQw4w9WgXcQ",
    lang="es"
)
print(f"Got translated transcript in {translated.lang}")

```

```bash
curl -X GET 'https://api.supadata.ai/v1/youtube/transcript/translate?videoId=dQw4w9WgXcQ&lang=es&text=true' \
  -H 'x-api-key: YOUR_API_KEY'

```

--------------------------------

### Manual Installation with npx

Source: https://docs.supadata.ai/integrations/mcp

Starts the Supadata MCP server locally using npx, passing the API key as an environment variable. Requires a valid SUPADATA_API_KEY.

```bash
env SUPADATA_API_KEY=your-api-key npx -y @supadata/mcp
```

--------------------------------

### Start batch job with Go

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-batch

Uses Go's net/http package to POST to the batch endpoint. The example includes videoIds, playlistId, channelId, and limit parameters. Requires an API key.

```Go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.supadata.ai/v1/youtube/video/batch"

	payload := strings.NewReader("{\n  \"videoIds\": [\n    \"dQw4w9WgXcQ\",\n    \"https://www.youtube.com/watch?v=xvFZjo5PgG0\"\n  ],\n  \"playlistId\": \"https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc\",\n  \"channelId\": \"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw\",\n  \"limit\": 20\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Go: Get YouTube channel

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel

Go example using net/http to make a GET request to the Supadata endpoint with the API key header. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.supadata.ai/v1/youtube/channel"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Fetch playlist using Go

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/playlist

Example of performing a GET request to the REST endpoint '/v1/youtube/playlist' in Go using net/http. Requires the 'x-api-key' header.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.supadata.ai/v1/youtube/playlist"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Start batch job with Ruby

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-batch

Uses Ruby's net/http library to POST to the batch endpoint. The example includes videoIds, playlistId, channelId, and limit parameters. Requires an API key.

```Ruby
require 'uri'
require 'net/http'

url = URI("https://api.supadata.ai/v1/youtube/video/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"videoIds\": [\n    \"dQw4w9WgXcQ\",\n    \"https://www.youtube.com/watch?v=xvFZjo5PgG0\"\n  ],\n  \"playlistId\": \"https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc\",\n  \"channelId\": \"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw\",\n  \"limit\": 20\n}"

response = http.request(request)
puts response.read_body
```

--------------------------------

### cURL Request Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Sends a GET request to the endpoint with the video ID or URL as a query parameter. Requires an API key in the x-api-key header.

```bash
curl -X GET "https://api.supadata.ai/v1/youtube/video?id=https://youtu.be/dQw4w9WgXcQ" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

--------------------------------

### Get YouTube transcript, metadata, channel, playlist, and batch operations

Source: https://docs.supadata.ai/integrations/python

Comprehensive example showing how to retrieve YouTube transcripts (with language preference, translation, plain text), video/channel/playlist metadata, video IDs from channels and playlists, and batch operations for transcripts and video metadata. Includes polling batch results and handling errors.

```Python
# Get YouTube transcript with Spanish language preference (universal transcript endpoint)
transcript = supadata.transcript(url="https://youtu.be/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.transcript(
    url="https://youtu.be/dQw4w9WgXcQ",
    text=True
)
print(text_transcript.content)

# Get Video Metadata (universal metadata endpoint)
video = supadata.metadata(url="https://youtu.be/dQw4w9WgXcQ")
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'}")

```

--------------------------------

### JavaScript fetch Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Uses the fetch API to make a GET request to the endpoint. Requires an API key in the x-api-key header.

```javascript
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.supadata.ai/v1/youtube/video', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Java Unirest Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Uses the Unirest HTTP library to make a GET request to the endpoint. Requires an API key in the x-api-key header.

```java
HttpResponse<String> response = Unirest.get("https://api.supadata.ai/v1/youtube/video")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### Start batch job with JavaScript fetch

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-batch

Uses the fetch API to POST to the batch endpoint. The example includes videoIds, playlistId, channelId, and limit parameters. Requires an API key.

```JavaScript
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    videoIds: ['dQw4w9WgXcQ', 'https://www.youtube.com/watch?v=xvFZjo5PgG0'],
    playlistId: 'https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc',
    channelId: 'https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw',
    limit: 20
  })
};

fetch('https://api.supadata.ai/v1/youtube/video/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Start batch job with Java Unirest

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-batch

Uses the Unirest HTTP library to POST to the batch endpoint. The example includes videoIds, playlistId, channelId, and limit parameters. Requires an API key.

```Java
HttpResponse<String> response = Unirest.post("https://api.supadata.ai/v1/youtube/video/batch")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"videoIds\": [\n    \"dQw4w9WgXcQ\",\n    \"https://www.youtube.com/watch?v=xvFZjo5PgG0\"\n  ],\n  \"playlistId\": \"https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc\",\n  \"channelId\": \"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw\",\n  \"limit\": 20\n}")
  .asString();
```

--------------------------------

### Go: Fetch channel videos

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel-videos

Uses Go's net/http package to send a GET request to the Supadata endpoint with an API key header. The example uses limit=30 and type=all.

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.supadata.ai/v1/youtube/channel/videos?limit=30&type=all"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Example tags array from response

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Example array of video tags as returned in the response schema.

```json
["Rick Astley", "Official Video", "Music"]
```

--------------------------------

### pip install supadata

Source: https://docs.supadata.ai/integrations/python

Install the Supadata Python SDK using pip.

```APIDOC
## [INSTALL] pip install supadata

### Description
Install the Supadata Python SDK using pip.

### Method
INSTALL

### Endpoint
pip install supadata

### Parameters
None

### Request Example
```
pip install supadata
```

### Response
#### Success Response (200)
- No response body

#### Response Example
```
Successfully installed supadata
```
```

--------------------------------

### Install Supadata Python SDK with pip

Source: https://docs.supadata.ai/integrations/python

Install the Supadata Python SDK using pip. Run this command in your terminal to install the package.

```bash
pip install supadata

```

--------------------------------

### Successful Response Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Example of a 200 response containing video metadata such as title, channel, duration, and statistics.

```json
{
  "id": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
  "description": "The official music video for \"Never Gonna Give You Up\"...",
  "duration": 213,
  "channel": {
    "id": "UCuAXFkgsw1L7xaCfnd5JJOw",
    "name": "Rick Astley"
  },
  "tags": [
    "Rick Astley",
    "Official Video",
    "Music"
  ],
  "transcriptLanguages": [
    "en",
    "es",
    "fr"
  ],
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
  "uploadDate": "2009-10-25T00:00:00.000Z",
  "viewCount": 1234567890,
  "likeCount": 12345678
}
```

--------------------------------

### Install @supadata/js with npm

Source: https://docs.supadata.ai/integrations/node

Install the Supadata Node SDK using npm. The command can be adapted for pnpm, yarn, or bun.

```bash
npm install @supadata/js

```

--------------------------------

### Start batch job with PHP cURL

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-batch

Uses PHP's cURL extension to POST to the batch endpoint. The example includes videoIds, playlistId, channelId, and limit parameters. Requires an API key.

```PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.supadata.ai/v1/youtube/video/batch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'videoIds' => [
        'dQw4w9WgXcQ',
        'https://www.youtube.com/watch?v=xvFZjo5PgG0'
    ],
    'playlistId' => 'https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc',
    'channelId' => 'https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw',
    'limit' => 20
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Response example for urls field

Source: https://docs.supadata.ai/api-reference/endpoint/web/map

Example value for the 'urls' field in the response, showing a list of URLs.

```json
[
  "https://supadata.ai",
  "https://docs.supadata.ai"
]
```

--------------------------------

### Example data object

Source: https://docs.supadata.ai/api-reference/endpoint/extract/extract-get

Example of the data object returned in the response, containing extracted topics and summary.

```json
{  
  "topics": [  
    "AI basics",  
    "Machine learning",  
    "Neural networks"  
  ],  
  "summary": "An introduction to artificial intelligence concepts"  
}
```

--------------------------------

### Python: Fetch channel videos with supadata package

Source: https://docs.supadata.ai/youtube/channel-videos

Initializes the Supadata client and calls supadata.youtube.channel.videos with a channel handle, type 'all', and limit 50. Prints the returned video, short, and live IDs.

```python
from supadata import Supadata, SupadataError

# Initialize the client
supadata = Supadata(api_key="YOUR_API_KEY")

channel_videos = supadata.youtube.channel.videos(
    id="RickAstleyVEVO",  # can be url, channel id, or handle
    type="all",  # 'all', 'video', 'short', or 'live'
    limit=50
)
print(f"Regular videos: {channel_videos.video_ids}")
print(f"Shorts: {channel_videos.short_ids}")
print(f"Live: {channel_videos.live_ids}")
```

--------------------------------

### Ruby: Get YouTube channel

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel

Ruby example using net/http to make a GET request to the Supadata endpoint with the API key header. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.supadata.ai/v1/youtube/channel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### PHP: Get YouTube channel with cURL

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel

PHP example using cURL to make a GET request to the Supadata endpoint. Includes error handling and prints the response.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.supadata.ai/v1/youtube/channel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Java (Unirest): Get YouTube channel

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel

Java example using Unirest to make a GET request to the Supadata endpoint with the API key header. Returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://api.supadata.ai/v1/youtube/channel")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### Start YouTube video metadata batch job (Python)

Source: https://docs.supadata.ai/youtube/batch

Initializes the Supadata client and starts a video metadata batch job using a playlist ID, with commented alternatives for video_ids and channel_id. Requires an API key and the supadata package.

```python
from supadata import Supadata

# Initialize the client
supadata = Supadata(api_key="YOUR_API_KEY")

video_batch_job = supadata.youtube.video.batch(
    playlist_id="PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc",
    limit=20
    # video_ids=["dQw4w9WgXcQ", "xvFZjo5PgG0"], # alternatively
    # channel_id="UC_9-kyTW8ZkZNDHQJ6FgpwQ", # alternatively
)
print(f"Started video metadata batch job: {video_batch_job.job_id}")
```

--------------------------------

### PHP cURL Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Uses PHP cURL to make a GET request to the endpoint. Requires an API key in the x-api-key header.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.supadata.ai/v1/youtube/video",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Go (net/http) - GET batch job

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/batch-get

Creates a GET request with the x-api-key header using the net/http package, reads the response body, and prints it. Ignores errors for brevity. Replace the URL and header values.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.supadata.ai/v1/youtube/batch/{jobId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

--------------------------------

### GET /v1/youtube/search

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/search

This snippet documents the YouTube search endpoint, including its query parameters, request example, response schema, and error responses.

```APIDOC
## GET /v1/youtube/search

### Description
Searches YouTube for videos, channels, or playlists based on a query string. Returns a list of results with metadata such as title, description, duration, view count, and channel information.

### Method
GET

### Endpoint
https://api.supadata.ai/v1/youtube/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string.
- **type** (string) - Optional - The type of results to return: 'video', 'channel', 'playlist', or 'all' (default 'all').
- **limit** (integer) - Optional - The maximum number of results to return. Use to get more than the first page of results.
- **sortBy** (string) - Optional - Sort order: 'relevance', 'rating', 'date', or 'views'.
- **uploadDate** (string) - Optional - Filter by upload date: 'hour', 'today', 'week', 'month', or 'year'.
- **duration** (string) - Optional - Filter by video duration: 'short', 'medium', or 'long'.

### Request Example
```
curl -X GET "https://api.supadata.ai/v1/youtube/search?query=rick%20astley%20never%20gonna%20give%20you%20up&type=video&limit=20&sortBy=views&uploadDate=month" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
- **query** (string) - The original search query.
- **results** (array) - List of search result objects.
  - **type** (string) - The type of result: 'video', 'channel', or 'playlist'.
  - **id** (string) - The YouTube ID of the result.
  - **title** (string) - The title of the result.
  - **description** (string) - The description of the result.
  - **thumbnail** (string) - URL of the thumbnail image.
  - **duration** (integer) - Duration in seconds (for videos).
  - **viewCount** (integer) - Number of views (for videos).
  - **uploadDate** (string) - ISO 8601 upload date (for videos).
  - **channel** (object) - Channel information (for videos).
    - **id** (string) - Channel ID.
    - **name** (string) - Channel name.
    - **thumbnail** (string) - Channel thumbnail URL.
  - **handle** (string) - Channel handle (for channels).
  - **videoCount** (integer) - Number of videos (for channels).
- **totalResults** (integer) - Total number of search results.
- **nextPageToken** (string) - Token for fetching the next page of results.

#### Response Example
```
{
  "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/..."
      },
      "handle": "@RickAstleyYT",
      "videoCount": 100
    }
  ],
  "totalResults": 1000000,
  "nextPageToken": "eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319"
}
```

### Error Handling
#### Error Response (400)
- **error** (string) - Error code.
- **message** (string) - Error message.
- **details** (string) - Detailed error description.
- **documentationUrl** (string) - URL to error documentation.

#### Error Response Example
```
{
  "error": "invalid-request",
  "message": "Invalid Request",
  "details": "The request is invalid or malformed",
  "documentationUrl": "https://docs.supadata.ai/errors#invalid-request"
}
```

#### Error Response (500)
- **error** (string) - Error code.
- **message** (string) - Error message.
- **details** (string) - Detailed error description.
- **documentationUrl** (string) - URL to error documentation.

#### Error Response Example
```
{
  "error": "invalid-request",
  "message": "Invalid Request",
  "details": "The request is invalid or malformed",
  "documentationUrl": "https://docs.supadata.ai/errors#invalid-request"
}
```
```

--------------------------------

### Success Response: Map website URLs

Source: https://docs.supadata.ai/api-reference/endpoint/web/map

Example 200 response containing a list of URLs for the mapped website.

```json
{
  "urls": [
    "https://supadata.ai",
    "https://docs.supadata.ai"
  ]
}
```

--------------------------------

### Python SDK Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Uses the supadata Python SDK to fetch video metadata. Requires an API key. The id parameter accepts a video ID or URL.

```python
from supadata import Supadata

supadata = Supadata(api_key="YOUR_API_KEY")
video = supadata.youtube.video(
    id="https://youtu.be/dQw4w9WgXcQ" # can be id or url
)
print(f"Video title: {video.title}")
print(f"Channel: {video.channel.name}")
```

--------------------------------

### Python: Initialize Supadata and call web.map

Source: https://docs.supadata.ai/web/map

Initializes the Supadata client with an API key and calls web.map to retrieve a sitemap for a given URL. Prints the number of URLs found.

```python
from supadata import Supadata, SupadataError

# Initialize the client
supadata = Supadata(api_key="YOUR_API_KEY")

site_map = supadata.web.map("https://supadata.ai")
print(f"Found {len(site_map.urls)} URLs")

```

--------------------------------

### Node.js SDK Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-get

Uses the @supadata/js SDK to fetch video metadata. Requires an API key. The id parameter accepts a video ID or URL.

```javascript
import { Supadata } from '@supadata/js';

const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY',
});
const video = await supadata.youtube.video({
  id: 'https://youtu.be/dQw4w9WgXcQ', // can be id or url
});
console.log(video.title);
```

--------------------------------

### TypeScript/Node.js Extract Job Example

Source: https://docs.supadata.ai/api-reference/endpoint/extract/extract

Initializes the Supadata client and starts an extract job on a YouTube URL, then retrieves the job results. Requires an API key.

```typescript
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: 'Extract the main topics and key takeaways',
});

// Get job results
const result = await supadata.extract.getResults(job.jobId);
console.log(result.data);
```

--------------------------------

### Start YouTube video metadata batch job (Node.js)

Source: https://docs.supadata.ai/youtube/batch

Initializes the Supadata client and starts a video metadata batch job using a playlist ID, with commented alternatives for videoIds and channelId. Requires an API key and the @supadata/js package.

```javascript
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}`);
```

--------------------------------

### PHP cURL: Fetch channel videos

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel-videos

Uses PHP cURL to send a GET request to the Supadata endpoint with an API key header. The example uses limit=30 and type=all.

```PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.supadata.ai/v1/youtube/channel/videos?limit=30&type=all",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Start a web crawl job with Supadata in Python

Source: https://docs.supadata.ai/web/crawl

Initializes the Supadata client with an API key and starts a crawl job for a URL with an optional limit. Prints the job ID to the console.

```python
from supadata import Supadata

# Initialize the client
supadata = Supadata(api_key="YOUR_API_KEY")

# Start a crawl job
crawl_job = supadata.web.crawl(
    url="https://supadata.ai",
    limit=100  # Optional: limit the number of pages to crawl
)
print(f"Started crawl job: {crawl_job.job_id}")

```

--------------------------------

### Ruby: Fetch channel videos

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel-videos

Uses Ruby's net/http library to send a GET request to the Supadata endpoint with an API key header. The example uses limit=30 and type=all.

```Ruby
require 'uri'
require 'net/http'

url = URI("https://api.supadata.ai/v1/youtube/channel/videos?limit=30&type=all")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Fetch transcript with Supadata client

Source: https://docs.supadata.ai/integrations/python

Initialize the Supadata client and fetch a transcript from a supported platform. This example shows the basic transcript call without handling async job status.

```python
from supadata import Supadata, SupadataError

# Initialize the client
supadata = Supadata(api_key="YOUR_API_KEY")

transcript = supadata.transcript(
    url="https://x.com/SpaceX/status/1481651037291225113",
    lang="en",  # Optional: preferred language
    text=True,  # Optional: return plain text instead of timestamped chunks
    mode="auto"  # Optional: "native", "auto", or "generate"
)

```

--------------------------------

### Get transcript directly with Supadata client

Source: https://docs.supadata.ai/integrations/node

Simplified example that initializes the client and fetches a transcript without explicit async job handling. Useful for smaller files where the transcript is returned directly.

```typescript
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), Facebook) 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'
});

```

--------------------------------

### limit Parameter Example

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/video-batch

Example of the limit parameter, which specifies the maximum number of videos to process. The default is 10 and the valid range is 1 to 5000.

```text
20
```

--------------------------------

### Java Unirest: Fetch channel videos

Source: https://docs.supadata.ai/api-reference/endpoint/youtube/channel-videos

Uses the Unirest HTTP library in Java to send a GET request to the Supadata endpoint with an API key header. The example uses limit=30 and type=all.

```Java
HttpResponse<String> response = Unirest.get("https://api.supadata.ai/v1/youtube/channel/videos?limit=30&type=all")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### GET /web/crawl/{jobId}

Source: https://docs.supadata.ai/api-reference/endpoint/web/crawl-get

Retrieves the status and results of a crawl job. Use the jobId from the crawl start response to fetch the crawled pages, with optional pagination via the skip query parameter.

```APIDOC
## GET /web/crawl/{jobId}

### Description
Retrieves the status and results of a crawl job. Use the jobId from the crawl start response to fetch the crawled pages, with optional pagination via the skip query parameter.

### Method
GET

### Endpoint
/web/crawl/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The crawl job ID

#### Query Parameters
- **skip** (number) - Optional - Number of results to skip for pagination. Must be >= 0.

### Response
#### Success Response (200)
- **status** (enum<string>) - Required - The status of the crawl job. Possible values: `scraping`, `completed`, `failed`, `cancelled`.
- **pages** (object[]) - List of pages that were crawled (only present when status is completed). Each page contains:
  - **url** (string) - The URL of the page.
  - **content** (string) - The text content of the page.
  - **countCharacters** (number) - The number of characters in the content.
  - **name** (string) - The page title.
  - **ogUrl** (string) - The Open Graph image URL.
- **next** (string) - URL for fetching the next page of results (the same endpoint with a `skip` offset). Only present when more pages are available.

#### Response Example
```json
{
  "status": "completed",
  "pages": [
    {
      "url": "https://supadata.ai",
      "content": "# Supadata\n## What is Supadata?\nSupadata is an API platform for data extraction for LLM training.",
      "countCharacters": 12300,
      "name": "Supadata: Web & YouTube to text API for developers",
      "ogUrl": "https://supadata.ai/opengraph-image.png"
    }
  ],
  "next": "https://api.supadata.ai/v1/web/crawl/123e4567-e89b-12d3-a456-426614174000?skip=10"
}
```

### Error Responses
#### 400 Bad Request
```json
{
  "error": "invalid-request",
  "message": "Invalid Request",
  "details": "The request is invalid or malformed",
  "documentationUrl": "https://docs.supadata.ai/errors#invalid-request"
}
```

#### 500 Internal Server Error
```json
{
  "error": "invalid-request",
  "message": "Invalid Request",
  "details": "The request is invalid or malformed",
  "documentationUrl": "https://docs.supadata.ai/errors#invalid-request"
}
```

### Authorizations
- **x-api-key** (string, header) - Required - API key for authentication.
```

--------------------------------

### Get Crawl Results with Supadata JavaScript SDK

Source: https://docs.supadata.ai/api-reference/endpoint/web/crawl-get

Use the Supadata JavaScript SDK to start a crawl job and retrieve its results. The `getCrawlResults` method automatically handles pagination and returns all pages.

```typescript
import { Supadata } from '@supadata/js';

const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY',
});

// Start a crawl job
const crawl = await supadata.web.crawl({
  url: 'https://example.com',
  limit: 10,
});

// Get crawl job results
// This automatically handles pagination and returns all pages
const crawlResults = await supadata.web.getCrawlResults(crawl.jobId);
console.log(crawlResults);
```

--------------------------------

### Get Job Results (Node.js, Python, cURL)

Source: https://docs.supadata.ai/get-extract

Poll for job results using the job ID endpoint. Shows Node.js, Python, and cURL examples for checking the status and retrieving data or error.

```javascript
// 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
# 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 -X GET "https://api.supadata.ai/v1/extract/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Fetch metadata with Go

Source: https://docs.supadata.ai/api-reference/endpoint/metadata/metadata

Uses the net/http package to send a GET request to the /metadata endpoint. Replace '<api-key>' with your actual API key. The response body is printed.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.supadata.ai/v1/metadata"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```
Tokens:
Raw