> ## Documentation Index > Fetch the complete documentation index at: https://docs.supadata.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search > Search YouTube for videos, channels, and playlists with advanced filters. ## OpenAPI ````yaml v1-openapi GET /youtube/search openapi: 3.1.0 info: title: Supadata description: Web & Social Media Content API for Developers version: 1.3.0 servers: - url: https://api.supadata.ai/v1 security: - apiKeyAuth: [] paths: /youtube/search: get: description: >- Search YouTube for videos, channels, and playlists with advanced filters. operationId: getYoutubeSearch parameters: - in: query name: query schema: type: string minLength: 1 description: Search query string example: Never Gonna Give You Up required: true - in: query name: uploadDate schema: type: string enum: - all - hour - today - week - month - year description: >- Filter by upload date (eg. last month). Note: works only for videos and movies. example: month default: all required: false - in: query name: type schema: type: string enum: - all - video - channel - playlist - movie description: Filter by content type example: video default: all required: false - in: query name: duration schema: type: string enum: - all - short - medium - long description: >- Filter by video duration: short (<4min), medium (4-20min), long (>20min). Note: works only for videos and movies. example: medium default: all required: false - in: query name: sortBy schema: type: string enum: - relevance - rating - date - views description: Sort order of search results. example: views default: relevance required: false - in: query name: features schema: type: array items: type: string enum: - hd - subtitles - creative-commons - 3d - live - 4k - '360' - location - hdr - vr180 description: >- Array of special features to filter by. Note: works only for videos and movies. example: - hd - subtitles - creative-commons required: false - in: query name: limit schema: type: number minimum: 1 maximum: 5000 description: >- Maximum number of results to return. When provided, the API will automatically paginate to fetch up to this many results. When omitted, returns a single page with `nextPageToken` for manual pagination. example: 50 required: false - in: query name: nextPageToken schema: type: string description: >- Token for fetching the next page of results. When provided, other filter parameters are ignored. example: eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319 required: false responses: '200': description: Successfully retrieved search results content: application/json: schema: $ref: '#/components/schemas/YoutubeSearch' '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: TypeScript label: Node.js source: |- 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`); - lang: Python label: Python source: |- from supadata import Supadata supadata = Supadata(api_key="YOUR_API_KEY") search_results = 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 sort_by="views", # Optional: 'relevance', 'rating', 'date', 'views' upload_date="year", # Optional: 'hour', 'today', 'week', 'month', 'year' duration="medium" # Optional: 'short', 'medium', 'long' ) print(f"Found {len(search_results.results)} results") for result in search_results.results: print(f"{result.type}: {result.title}") - lang: Shell label: cURL source: >- curl -X GET "https://api.supadata.ai/v1/youtube/search?query=rick%20astley%20never%20gonna%20give%20you%20up&type=video&limit=20&sortBy=views&uploadDate=month" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" components: schemas: YoutubeSearch: type: object properties: query: type: string description: The search query that was executed example: Rick Astley Never Gonna Give You Up results: type: array items: type: object properties: type: type: string enum: - video - channel - playlist description: Type of the search result example: video id: type: string description: ID of the video, channel, or playlist example: dQw4w9WgXcQ title: type: string description: Title of the result example: Rick Astley - Never Gonna Give You Up (Official Video) description: type: string description: Description of the result example: The official music video for Rick Astley... thumbnail: type: string description: URL to the thumbnail image example: https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg duration: type: number description: Duration in seconds (for videos only) example: 213 viewCount: type: number description: View count (for videos only) example: 1234567890 uploadDate: type: string description: Upload date (for videos only) example: '2009-10-25T00:00:00.000Z' format: date-time channel: type: object properties: id: type: string description: Channel ID example: UCuAXFkgsw1L7xaCfnd5JJOw name: type: string description: Channel name example: Rick Astley thumbnail: type: string description: Channel thumbnail URL example: https://yt3.ggpht.com/... required: - id - name description: Channel information (for videos and playlists) subscriberCount: type: number description: Subscriber count (for channels only) example: 2000000 videoCount: type: number description: Video count (for channels and playlists only) example: 100 required: - type - id - title description: Search result item description: Array of search results totalResults: type: number description: Estimated total number of results example: 1000000 nextPageToken: type: string description: >- Token for fetching the next page of results. Only returned when limit parameter is not provided. example: eyJxdWVyeSI6IlJpY2sgQXN0bGV5IiwiZmlsdGVycyI6e319 required: - query - results Error: type: object properties: error: type: string enum: - invalid-request - internal-error - forbidden - unauthorized - upgrade-required - transcript-unavailable - not-found - limit-exceeded description: Error code identifying the type of error example: invalid-request message: type: string description: Human readable error message example: Invalid Request details: type: string description: Detailed error description example: The request is invalid or malformed documentationUrl: type: string description: URL to error documentation example: https://supadata.ai/documentation/errors#invalid-request required: - error - message - details description: Standard error response format securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key ````