Skip to main content
GET
/
youtube
/
search
import { Supadata } from '@supadata/js';

const supadata = new Supadata({
  apiKey: 'YOUR_API_KEY',
});
const searchResults = await supadata.youtube.search({
  query: 'rick astley 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'
});
console.log(`Found ${searchResults.results.length} results`);
{
  "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/..."
      },
      "subscriberCount": 2000000,
      "videoCount": 100
    }
  ],
  "totalResults": 1000000,
  "nextPageToken": "eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319"
}

Authorizations

​
x-api-key
string
header
required

Query Parameters

​
query
string
required

Search query string

Minimum length: 1
Example:

"Never Gonna Give You Up"

​
uploadDate
enum<string>
default:all

Filter by upload date (eg. last month). Note: works only for videos and movies.

Available options:
all,
hour,
today,
week,
month,
year
Example:

"month"

​
type
enum<string>
default:all

Filter by content type

Available options:
all,
video,
channel,
playlist,
movie
Example:

"video"

​
duration
enum<string>
default:all

Filter by video duration: short (<4min), medium (4-20min), long (>20min). Note: works only for videos and movies.

Available options:
all,
short,
medium,
long
Example:

"medium"

​
sortBy
enum<string>
default:relevance

Sort order of search results.

Available options:
relevance,
rating,
date,
views
Example:

"views"

​
features
enum<string>[]

Array of special features to filter by. Note: works only for videos and movies.

Example:
["hd", "subtitles", "creative-commons"]
​
limit
number

Maximum number of results to return. When provided, the API will automatically paginate to fetch up to this many results. When omitted, returns a single page with nextPageToken for manual pagination.

Required range: 1 <= x <= 5000
Example:

50

​
nextPageToken
string

Token for fetching the next page of results. When provided, other filter parameters are ignored.

Example:

"eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319"

Response

Successfully retrieved search results

​
query
string
required

The search query that was executed

Example:

"Rick Astley Never Gonna Give You Up"

​
results
object[]
required

Array of search results

​
totalResults
number

Estimated total number of results

Example:

1000000

​
nextPageToken
string

Token for fetching the next page of results. Only returned when limit parameter is not provided.

Example:

"eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319"

⌘I