Skip to main content
GET
/
api
/
search
Search Videos
curl --request GET \
  --url https://api.example.com/api/search
{
  "results": [
    {
      "id": "<string>",
      "title": "<string>",
      "thumbnail": "<string>",
      "duration": 123,
      "uploader": "<string>",
      "url": "<string>",
      "view_count": 123
    }
  ]
}
Search for YouTube videos by query or fetch information from a direct URL.

​
Query Parameters

​
q
string
required
Search query or YouTube URL. Can be:
  • Search keywords (e.g., “python tutorial”)
  • Direct YouTube video URL
  • YouTube playlist URL
​
max_results
integer
default:"20"
Maximum number of results to return (1-50)

​
Response

​
results
array
Array of video objects matching the search criteria

​
Example Request

​
Search by Keywords

curl -X GET "http://localhost:8001/api/search?q=python+tutorial&max_results=10"

​
Search by URL

curl -X GET "http://localhost:8001/api/search?q=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

​
Example Response

{
  "results": [
    {
      "id": "dQw4w9WgXcQ",
      "title": "Python Tutorial for Beginners",
      "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "duration": 3600,
      "uploader": "Tech Academy",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "view_count": 1500000
    },
    {
      "id": "abc123def45",
      "title": "Advanced Python Programming",
      "thumbnail": "https://i.ytimg.com/vi/abc123def45/hqdefault.jpg",
      "duration": 7200,
      "uploader": "Code Masters",
      "url": "https://www.youtube.com/watch?v=abc123def45",
      "view_count": 850000
    }
  ]
}

​
Error Responses

​
400 Bad Request

Returned when the q parameter is missing or empty. 
{
  "detail": "El parámetro 'q' es requerido"
}

​
500 Internal Server Error

Returned when the search operation fails. 
{
  "detail": "Error en búsqueda: [error message]"
}

​
Implementation Notes

  • When q starts with http, the endpoint treats it as a direct URL and extracts video info
  • For search queries, uses YouTube’s search functionality via yt-dlp
  • Results are limited by max_results parameter (default: 20)
  • Thumbnail URLs use YouTube’s hqdefault quality for consistent sizing