Documentation Index
Fetch the complete documentation index at: https://mintlify.com/vsmutok/ytscrape/llms.txt
Use this file to discover all available pages before exploring further.
The YouTube.search() method is the primary way to query YouTube. It accepts a text query and an optional filter and returns a SearchResults object — a lazy, paginated iterable that streams results across as many pages as you need.
Basic search
With no filter applied, YouTube returns a mixed feed of videos, channels, and playlists. Iterate directly over the results to consume them one at a time; pages are loaded on demand.
from ytscrape import YouTube
with YouTube() as yt:
for item in yt.search("python tutorial"):
print(item.title, item.url)
max_results to stop after a fixed number of items:
with YouTube() as yt:
for item in yt.search("python tutorial", max_results=10):
print(item.title)
Filtering by result type
Import SearchFilter and pass it as the filter keyword argument to restrict results to a single content type.
| Filter | String value | Description |
|---|
SearchFilter.ALL | "all" | Mixed feed — videos, channels, and playlists (default) |
SearchFilter.VIDEOS | "videos" | Videos only |
SearchFilter.CHANNELS | "channels" | Channels only |
SearchFilter.PLAYLISTS | "playlists" | Playlists only |
SearchFilter.SHORTS | "shorts" | YouTube Shorts only |
SearchFilter.MOVIES | "movies" | Movies only |
Videos
from ytscrape import YouTube, SearchFilter
with YouTube() as yt:
results = yt.search(
"python tutorial",
filter=SearchFilter.VIDEOS,
max_results=10,
)
for video in results:
print(f"{video.title} ({video.duration})")
print(f" by {video.channel} — {video.views}")
print(f" {video.url}")
Channels
from ytscrape import YouTube, SearchFilter
with YouTube() as yt:
for channel in yt.search("python", filter=SearchFilter.CHANNELS, max_results=5):
print(f"{channel.title} — {channel.subscribers}")
print(f" {channel.url}")
Playlists
from ytscrape import YouTube, SearchFilter
with YouTube() as yt:
for playlist in yt.search("python", filter=SearchFilter.PLAYLISTS, max_results=5):
print(f"{playlist.title} ({playlist.video_count} videos)")
print(f" {playlist.url}")
Using string values instead of the enum
Every SearchFilter member has an equivalent lowercase string value. You can pass it directly without importing the enum:
with YouTube() as yt:
for video in yt.search("lofi", filter="videos", max_results=5):
print(video.title)
"all", "videos", "channels", "playlists", "shorts", and "movies". An unrecognised value raises ValueError immediately.
The max_results parameter
max_results caps the total number of items yielded during iteration. Once that count is reached the iterator stops cleanly, even if YouTube has more pages.
with YouTube() as yt:
# Fetch at most 25 results across however many pages that requires.
for video in yt.search("machine learning", filter="videos", max_results=25):
print(video.title)
max_results entirely to consume every result YouTube returns for the query.
Return type: SearchResults
yt.search() returns a SearchResults object. It is a lazy iterable — the first page of results is fetched when search() is called, and additional pages are fetched automatically as you consume items past the end of each page.
You can also drive pagination manually — see the Pagination guide for details.
Result field reference
Each yielded item is a frozen, fully typed dataclass. The concrete type depends on the active filter.
Video — returned by ALL and VIDEOS
| Field | Type | Description |
|---|
video_id | str | Unique 11-character YouTube video id |
title | str | None | Video title |
channel | str | None | Display name of the uploading channel |
channel_id | str | None | UC… channel id |
duration | str | None | Formatted duration string (e.g. "10:32") |
views | str | None | View count as rendered by YouTube (e.g. "1.2M views") |
published | str | None | Relative publish time (e.g. "3 days ago") |
thumbnail | str | None | URL of the largest available thumbnail |
url | str | Canonical https://www.youtube.com/watch?v=… URL (computed property) |
Channel — returned by ALL and CHANNELS
| Field | Type | Description |
|---|
channel_id | str | UC… channel id |
title | str | None | Channel display name |
handle | str | None | @handle when available |
subscribers | str | None | Subscriber count as rendered by YouTube (e.g. "1.23M subscribers") |
video_count | str | None | Public video count |
thumbnail | str | None | URL of the channel avatar |
url | str | Canonical https://www.youtube.com/channel/UC… URL (computed property) |
Playlist — returned by ALL and PLAYLISTS
| Field | Type | Description |
|---|
playlist_id | str | Unique playlist id |
title | str | None | Playlist title |
channel | str | None | Name of the channel that owns the playlist |
video_count | str | None | Number of videos in the playlist |
thumbnail | str | None | URL of the playlist thumbnail |
url | str | Canonical https://www.youtube.com/playlist?list=… URL (computed property) |
Create one YouTube instance and reuse it across multiple searches. The instance holds a warm HTTP session and a cached InnerTube context, so subsequent calls skip the initial context-extraction request and run noticeably faster.
