# Video search with [videos_search](../reference/videos_search.md#serpapi_search_tools.videos_search)

[videos_search](../reference/videos_search.md#serpapi_search_tools.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`](web_search.md) 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

``` python
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 the main YouTube result sections; use [SearchResultMode.FULL](../reference/SearchResultMode.md#serpapi_search_tools.SearchResultMode.FULL) to keep supporting sections and all fields on retained results |
| `response_format` | `markdown` | Return Markdown by default, or use [SearchResultFormat.JSON](../reference/SearchResultFormat.md#serpapi_search_tools.SearchResultFormat.JSON) for structured fields |
| `result_limit` | `10` | Maximum entries retained from each supported YouTube result list in either mode |
| `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:

``` python
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

Both modes apply `result_limit` independently to videos, Shorts, channels, playlists, movies, and categories, keeping up to 10 items in each list by default. Entries commonly include a title, link, thumbnail, channel, duration, views, and publication information. Use full mode when application code needs supporting response sections or additional result fields. Add `result_limit=None` to keep every returned item.


# 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

- [YouTube Search API](https://serpapi.com/youtube-search-api)

See the [video discovery recipe](recipes.md) and the [smolagents example](../docs/sdk-examples/smolagents.md).