Search YouTube
youtube_searchSearch YouTube for videos, channels, or playlists by query with filters for date, region, language, channel, and sort order.
Instructions
Search YouTube for videos, channels, and/or playlists using the YouTube Data API v3 search.list endpoint.
IMPORTANT — Quota cost: Every call to this tool costs 100 quota units (vs. 1 for most other tools). Use it sparingly and narrow the query as much as possible before calling.
Args:
query(required) — Free-text search query (e.g., "typescript tutorial 2024").type— Comma-separated list of resource types to return. Allowed values:video,channel,playlist. Default:"video".channelId— Restrict results to a specific channel's content. Optional.order— Sort order:relevance(default),date,rating,title,viewCount.maxResults— Number of results to return (1–50, default 25).pageToken— Pagination cursor from a previous response'snextPageToken. Optional.publishedAfter— Only return results published after this RFC 3339 datetime (e.g.,"2024-01-01T00:00:00Z"). Optional.publishedBefore— Only return results published before this RFC 3339 datetime. Optional.regionCode— ISO 3166-1 alpha-2 code to bias results (e.g.,"US"). Defaults to server default.relevanceLanguage— ISO 639-1 language code to bias relevance (e.g.,"en"). Optional.forMine— Whentrue, restricts results to the authenticated user's own videos. Requirestypeto include only"video". Optional.response_format—"markdown"(default) or"json".
Returns (JSON shape):
{
"nextPageToken": "string | null",
"pageInfo": { "totalResults": 1234, "resultsPerPage": 25 },
"items": [
{
"kind": "youtube#searchResult",
"id": { "kind": "youtube#video", "videoId": "abc123" },
"snippet": {
"publishedAt": "2024-01-15T12:00:00Z",
"channelId": "UCxxx",
"title": "Result title",
"description": "Short description...",
"thumbnails": { "default": { "url": "..." } },
"channelTitle": "Channel Name",
"liveBroadcastContent": "none"
}
}
]
}Examples:
Search for recent TypeScript videos:
{ "query": "typescript tutorial", "order": "date", "maxResults": 10 }Search own channel for a topic:
{ "query": "react hooks", "forMine": true, "type": "video" }Paginate to the next page:
{ "query": "nodejs", "pageToken": "<nextPageToken from previous call>" }
Common Errors:
403 quotaExceeded— Daily quota exhausted (each call costs 100 units). Try again after midnight Pacific time.400 invalidSearchFilter— Conflicting filters, e.g.forMine:truewithtypecontaining non-video values.401 / 403 authError— Credentials missing or expired; re-runnpm run auth.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Free-text search query string. | |
| type | No | Comma-separated list of resource types: video, channel, playlist. Default: "video". | video |
| channelId | No | Restrict results to a specific channel ID. | |
| order | No | Sort order for results. One of: relevance (default), date, rating, title, viewCount. | relevance |
| maxResults | No | Number of results to return (1–50). Default: 25. | |
| pageToken | No | Pagination cursor. Pass the nextPageToken from a previous response to get the next page. | |
| publishedAfter | No | RFC 3339 datetime — only return results published after this time (e.g. 2024-01-01T00:00:00Z). | |
| publishedBefore | No | RFC 3339 datetime — only return results published before this time. | |
| regionCode | No | ISO 3166-1 alpha-2 region code to bias results (e.g. "US"). Defaults to US. | |
| relevanceLanguage | No | ISO 639-1 language code to bias relevance ranking (e.g. "en"). | |
| forMine | No | When true, restricts search to the authenticated user's own videos. Requires type to be "video" only. | |
| response_format | No | Output format: "markdown" (default, human-readable) or "json" (full structured data). | markdown |