Video search with videos_search

videos_search searches YouTube for videos, channels, and playlists. It gives an agent a simple query field while the package sends YouTube’s native search_query parameter.

When to use it

Use it for tutorials, demonstrations, talks, reviews, interviews, channels, and playlists. Choose web_search when a text source is more appropriate.

This tool searches YouTube results. It does not fetch a video’s transcript or the separate video-detail API.

Quick example

from serpapi_search_tools import videos_search

tutorial_search = videos_search()
agent_tools = [tutorial_search]

Inputs the agent can provide

Field Type Required Meaning
query string yes The topic, tutorial, creator, or video to find

Use the consistent query field shown above. The package translates it to YouTube’s search_query parameter.

Configure the tool

Constructor option Default Use it for
provider "auto" Detect one installed SDK or select one explicitly
default_params None Fix locale or supported YouTube search filters
mode compact Return up to five video results; use SearchResultMode.FULL for the untouched response
api_key None Override environment key lookup
timeout None Set the built-in client timeout
client None Add caching, logging, tests, or response reduction
include_examples True Add a sample video query to the description
name "videos_search" Rename a focused video-search capability

Useful SerpApi parameters

This example fixes language and country preferences:

from serpapi_search_tools import videos_search

english_videos = videos_search(
    default_params={"hl": "en", "gl": "us"},
    name="english_video_search",
)

YouTube search also accepts a filter token for narrowing result type, date, duration, and other search choices. Use the official reference to obtain a valid token rather than inventing filter fields.

What comes back

Compact mode returns up to five video_results. Entries commonly include title, link, thumbnail, channel, duration, views, and publication information. Use full mode when application code needs auxiliary channel or playlist sections.

Common mistakes

  • Calling the tool with search_query; use query.
  • Expecting transcript text from a search response.
  • Treating channel and playlist entries as if they have video-only fields.
  • Opting into full results for a model when compact video results are enough.

Official SerpApi documentation

See the video discovery recipe and the smolagents example.