youtube_search
YouTube search with cursor pagination — typed hits, ids, canonical URLs, filters (2 credits/page, 0 when a page finds nothing). Costs 2 credits. Empty results and failures are never charged. Pass cache=true for a free 24h cache hit (default always fresh).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"q": "<q>"
},
"name": "youtube_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query or keywords (min 2 characters). | |
| type | No | all | videos | shorts | channels | playlists. | |
| cache | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. | |
| limit | No | Max items to return (default 20, max 200). Flat 2 credits per call. | |
| cursor | No | Pagination cursor. Leave empty for the first page; then pass the nextCursor value returned in the previous response. | |
| fields | No | Optional comma-separated keys to keep on each result row (or on the object for single-item tools), e.g. id,url,publishedAt,engagement. Pagination keys are always kept. Does not change the price. | |
| region | No | ISO country code for localized results (default US). | |
| sortBy | No | relevance | views (alias: popular→views). date and rating answer 400 SORT_NOT_SUPPORTED: YouTube no longer orders search by upload date (use uploadDate) or by rating. With type=shorts only relevance is supported. | |
| compact | No | Default true here: drop signed media URLs (video, image, avatar links and their expiry stamps) to keep the response small. Ids, permalinks, dates, text and metrics stay. On Threads, Facebook, Meta Ad Library and TikTok Shop tools request timings are dropped too. Pass false for the full body. | |
| duration | No | any | under_4 | 4_20 | over_20. Applies to long-form videos (not Shorts). | |
| uploadDate | No | any | today | this_week | this_month | this_year. |