- Início
- Documentação
- search_videos
search_videos
Encontre vídeos do YouTube por uma consulta de texto. Cada chamada devolve uma página com apenas vídeos, em geral cerca de 20 resultados.
Pesquisar vídeos do YouTube. REST: POST /v1/search
Parâmetros
Envie uma consulta e, se desejar, o idioma e a região dos resultados.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
query | string | Sim | Consulta com 1 a 200 caracteres depois de remover espaços no início e no fim. |
language | string | Não | Idioma dos resultados, usado como hl. Exemplo: pt. |
region | string | Não | Região ISO 3166-1 alpha-2, usada como gl. Exemplo: BR. |
cursor | string | Não | Cursor opaco em base64url recebido em nextCursor. Omita na primeira página. |
Exemplos
O exemplo procura uma oficina fictícia do próprio usuário.
Encontre a oficina Planilha do zero para pequenos negócios do meu canal.
O assistente chama search_videos com {"query": "Planilha do zero para pequenos negócios Meu canal", "language": "pt", "region": "BR"}.
curl -X POST https://mcp.mcptube.com/v1/search \ -H "Authorization: Bearer mct_SUA_CHAVE" \ -H "Content-Type: application/json" \ -d '{"query": "Planilha do zero para pequenos negócios Meu canal", "language": "pt", "region": "BR"}'
Resposta
Na API REST, o resultado vem diretamente em JSON com HTTP 200, sem job.
{
"results": [
{
"videoId": "MinhaAula_0",
"url": "https://www.youtube.com/watch?v=MinhaAula_0",
"title": "Planilha do zero para pequenos negócios",
"channel": "Meu canal",
"channelId": "UCa9Rk2pLm7QwX4sTn1vB3cE",
"durationSeconds": 2520,
"uploadDate": "2026-10-21",
"viewCount": 1240,
"thumbnailUrl": "https://i.ytimg.com/vi/MinhaAula_0/hqdefault.jpg",
"isLive": false
}
],
"nextCursor": null
}| Campo | Descrição |
|---|---|
results | Lista de vídeos. Canais, playlists e outros tipos de resultado não são incluídos. Pode vir vazia ou com menos de 20 vídeos. |
results[].videoId, results[].url | ID e endereço canônico do vídeo. |
results[].title, results[].channel, results[].channelId | Título, nome e ID do canal. |
results[].durationSeconds | Duração em segundos ou null quando indisponível. |
results[].uploadDate | Data ISO quando possível, texto de publicação como há 2 dias, ou null quando indisponível. |
results[].viewCount | Número de visualizações ou null quando indisponível. |
results[].thumbnailUrl, results[].isLive | Endereço da miniatura e indicação de transmissão ao vivo. |
nextCursor | Cursor opaco em base64url para a próxima página, ou null quando não houver outra página. |
Para continuar, envie nextCursor no campo cursor, mantendo a consulta, o idioma e a região. Não interprete nem altere o cursor. Cada próxima página é uma nova chamada.
Limites
Cada página concluída, mesmo vazia, usa 1 unidade de metadataPerDay, compartilhado com get_video_info e get_video_comments, incluindo POST /v1/info e POST /v1/comments. Não usa a cota de transcrições. Falhas e bloqueios não são cobrados.
| Limite | Gratuito | Starter | Pro |
|---|---|---|---|
| Metadados por dia | 50 | 600 | 5.000 |
| Chamadas por minuto, compartilhadas | 10 | 10 | 10 |
O limite de 10 chamadas por minuto é compartilhado por search_videos, get_video_info, get_video_comments e get_usage, incluindo as rotas REST correspondentes. OAuth e todas as chaves da conta dividem os limites. O contador diário renova à 0h UTC.
Erros
Use o código para escolher o próximo passo.
| Situação | Código | HTTP | O que fazer |
|---|---|---|---|
| Consulta ou parâmetro inválido | invalid_request | 400 | Conferir os parâmetros |
| Credencial ausente ou inválida | unauthorized | 401 | Conectar a conta ou conferir a chave |
| Muitas chamadas por minuto | rate_limited | 429 | Aguardar o tempo indicado em Retry-After |
| Limite diário de metadados atingido | metadata_daily_limit | 429 | Aguardar até 0h UTC |
| Serviço temporariamente indisponível | youtube_blocked, service_unavailable | 503 | Tentar mais tarde |