Home
Documentation
search_videos

search_videos

Find YouTube videos with a text query. Each call returns one page containing only videos, usually around 20 results.

Search YouTube videos. REST: POST /v1/search

Parameters

Send a query and, optionally, a language and region for the results.

Name	Type	Required	Description
`query`	string	Yes	Query with 1 to 200 characters after trimming leading and trailing whitespace.
`language`	string	No	Results language, used as `hl`. Example: `en`.
`region`	string	No	ISO 3166-1 alpha-2 region, used as `gl`. Example: `US`.
`cursor`	string	No	Opaque base64url cursor received in `nextCursor`. Omit on the first page.

Examples

The example searches for the user's own fictional workshop.

TEXT

Find the Small business spreadsheets from scratch workshop from my channel.

Your assistant calls search_videos with {"query": "Small business spreadsheets from scratch My channel", "language": "en", "region": "US"}.

curl

curl -X POST https://mcp.mcptube.com/v1/search \
  -H "Authorization: Bearer mct_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Small business spreadsheets from scratch My channel", "language": "en", "region": "US"}'

Response

The REST API returns the result directly as JSON with HTTP 200, without a job.

200 OK

{
  "results": [
    {
      "videoId": "MinhaAula_0",
      "url": "https://www.youtube.com/watch?v=MinhaAula_0",
      "title": "Small business spreadsheets from scratch",
      "channel": "My channel",
      "channelId": "UCa9Rk2pLm7QwX4sTn1vB3cE",
      "durationSeconds": 2520,
      "uploadDate": "2026-10-21",
      "viewCount": 1240,
      "thumbnailUrl": "https://i.ytimg.com/vi/MinhaAula_0/hqdefault.jpg",
      "isLive": false
    }
  ],
  "nextCursor": null
}

Field	Description
`results`	List of videos. Channels, playlists and other result types are excluded. May be empty or contain fewer than 20 videos.
`results[].videoId`, `results[].url`	Video ID and canonical URL.
`results[].title`, `results[].channel`, `results[].channelId`	Title, channel name and channel ID.
`results[].durationSeconds`	Duration in seconds, or `null` when unavailable.
`results[].uploadDate`	ISO date when possible, published text such as `2 days ago`, or `null` when unavailable.
`results[].viewCount`	Number of views, or `null` when unavailable.
`results[].thumbnailUrl`, `results[].isLive`	Thumbnail URL and whether the video is live.
`nextCursor`	Opaque base64url cursor for the next page, or `null` when there are no more pages.

To continue, send nextCursor as cursor, keeping the same query, language and region. Do not interpret or change the cursor. Each next page is a new call.

Limits

Each successful page, even empty, uses 1 unit of metadataPerDay, shared with get_video_info and get_video_comments, including POST /v1/info and POST /v1/comments. It does not use the transcription quota. Failures and blocked requests are not charged.

Limit	Free	Starter	Pro
Metadata per day	50	600	5,000
Calls per minute, shared	10	10	10

The limit of 10 calls per minute is shared by search_videos, get_video_info, get_video_comments and get_usage, including the corresponding REST routes. OAuth and all account keys share the limits. The daily counter resets at 00:00 UTC.

Errors

Use the code to choose the next step.

Situation	Code	HTTP	What to do
Invalid query or parameter	`invalid_request`	400	Check the parameters
Missing or invalid credential	`unauthorized`	401	Connect your account or check the key
Too many calls per minute	`rate_limited`	429	Wait for the time in Retry-After
Daily metadata limit reached	`metadata_daily_limit`	429	Wait until 00:00 UTC
Service temporarily unavailable	`youtube_blocked`, `service_unavailable`	503	Try again later

See plans and quota and all error codes.