> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube API

> Busca en YouTube y lee videos, comentarios, canales, subidas de canales y transcripciones como JSON, con vistas, me gusta, fechas de publicación, capítulos y texto de subtítulos.

Lee datos públicos de YouTube como JSON mediante la API de tareas asíncronas. Envía `taskType` `SOCIAL` con `platform` `youtube` y elige qué leer con `action`. Cada solicitud completada cuesta **0.5 créditos**.

## Solicitud

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "SOCIAL", "payload": { "platform": "youtube", "action": "search", "query": "wireless earbuds review", "limit": 10 } }'
```

Envía la tarea y luego consulta `GET /v1/async/task/{id}` o recibe su webhook. Consulta [Tareas asíncronas](https://docs.querying.ai/es/concepts/async-tasks.md).

## Acciones

| `action` | Qué lee | Obligatorio |
| - | - | - |
| `search` (por defecto) | Resultados de búsqueda de YouTube | `query` |
| `recent` | Las subidas más recientes para una consulta, de la más nueva a la más antigua | `query` |
| `video` | La página de reproducción de un video | `videoId` |
| `comments` | Los comentarios de un video y sus respuestas | `videoId` |
| `channel` | Los datos y enlaces de un canal | `channel` |
| `channel_videos` | Los videos, Shorts o transmisiones en vivo de un canal | `channel` |
| `transcript` | Los subtítulos de un video | `videoId` |

`videoId` acepta un ID de video o una URL de video de YouTube (reproducción, `youtu.be`, Shorts o insertado). `channel` acepta un ID de canal (`UC...`), un `@handle` o una URL de canal.

## Parámetros

`search` y `recent`:

* `query`: Obligatorio. La consulta de búsqueda.
* `limit`: Entero opcional de 1 a 50, con 10 por defecto.
* `type`: `video` (por defecto), `all`, `shorts`, `channel`, `playlist` o `movie`.
* `order`: `relevance` (por defecto), `viewCount`, `date` o `rating`. `date` lista las subidas de la más nueva a la más antigua, como `recent`. `rating` ordena por número de me gusta los resultados más vistos de YouTube. Las búsquedas de `channel` y `playlist` aceptan `relevance` o `viewCount`.
* `publishedAfter`: Una hora ISO 8601, como `2026-11-01T00:00:00Z`. Devuelve los videos publicados después de ella.
* `videoDuration`: `short` (menos de 3 minutos), `medium` (de 3 a 20 minutos) o `long` (más de 20 minutos).
* `features`: Cualquiera de `live`, `4k`, `hd`, `subtitles`, `creative_commons`, `360`, `vr180`, `3d`, `hdr`, `location` y `purchased`, como array o como cadena separada por comas.
* `exactSpelling`: `true` busca la consulta tal como está escrita, sin la corrección ortográfica de YouTube.
* `pageToken`: El `nextPageToken` de la página anterior. Las búsquedas de videos ordenadas por `relevance` o `viewCount` sin `publishedAfter` devuelven uno, y cada página omite todos los videos que devolvieron las páginas anteriores.
* `regionCode` y `languageCode`: La región de YouTube (`US`, `KR`, `JP`) y el idioma de la interfaz (`en`, `ko`, `ja`) en que se busca.

`comments`:

* `limit`: Entero opcional de 1 a 500, con 100 por defecto. Las respuestas cuentan para el límite.
* `order`: `relevance` (por defecto, los comentarios destacados de YouTube) o `time` (los más nuevos primero).
* `includeReplies`: Opcional, con `true` por defecto.

`channel_videos`:

* `tab`: `videos` (por defecto), `shorts` o `streams`.
* `sort`: `latest` (por defecto), `popular` o `oldest`.
* `limit`: Entero opcional de 1 a 50, con 20 por defecto.

`transcript`:

* `languages`: Idiomas de subtítulos en orden de preferencia, como `["en", "ko"]`. Sin este parámetro se leen los subtítulos predeterminados del video, luego los de inglés y luego la primera pista.
* `isGenerated`: `true` lee solo los subtítulos automáticos, y `false`, solo los del autor del video.
* `trackName`: El nombre de la pista de subtítulos que se lee.
* `translateTo`: Un código de idioma. YouTube traduce los subtítulos a ese idioma.
* `maxSegments`: Entero opcional de 1 a 5.000, con 2.000 por defecto.

## Ejemplo de respuesta

```json theme={"theme":"css-variables"}
{
  "platform": "youtube",
  "action": "search",
  "query": "wireless earbuds review",
  "order": "relevance",
  "totalResults": 4523475,
  "returnedCount": 1,
  "videos": [
    {
      "position": 1,
      "videoId": "YdJh6QdOGME",
      "url": "https://www.youtube.com/watch?v=YdJh6QdOGME",
      "title": "Earbuds Awards 2026 - Best Bluetooth Earbuds by Category!",
      "channelId": "UCZZ4ivUawsXRktLKej8d6Xw",
      "channelTitle": "Mike O'Brien",
      "channelHandle": "@MikeOBrienMedia",
      "channelIsVerified": true,
      "publishedAt": "2026-11-17T15:39:37Z",
      "publishedTimeText": "21 hours ago",
      "duration": "PT16M35S",
      "durationSeconds": 995,
      "viewCount": 62618,
      "likeCount": 957,
      "category": "Science & Technology",
      "badges": ["New"],
      "thumbnails": { "high": "https://i.ytimg.com/vi/YdJh6QdOGME/hqdefault.jpg" }
    }
  ],
  "nextPageToken": "eyJyIjpbIllkSmg2UWRPR01FIl19"
}
```

## Campos del resultado

* Cada respuesta repite `platform` y `action`. Las listas incluyen `returnedCount`.
* `search` y `recent` devuelven `videos`. Cada video tiene `position`, `videoId`, `url`, `title`, `description`, los `channelId`, `channelTitle`, `channelHandle`, `channelUrl`, `channelThumbnail` y `channelIsVerified` del canal, `publishedAt`, `publishedTimeText`, `duration` (ISO 8601), `durationSeconds`, `viewCount`, `likeCount`, `category`, `thumbnails`, `richThumbnail` (la vista previa animada), `badges` e `isFamilySafe`. Una película añade `movie` con su póster, género, año, reparto y director.
* Una búsqueda también devuelve los `channels`, `playlists`, `shorts` y `shelves` que muestra la página de resultados, `totalResults` (la estimación de YouTube) y `didYouMean` o `showingResultsFor` cuando YouTube corrige la consulta.
* `video` añade `tags`, `commentCount`, `subscriberCount`, `hasCaptions`, `chapters`, `mostReplayed`, `music`, `descriptionLinks` y `relatedVideos`. Los capítulos del autor van primero, y los capítulos automáticos llevan `autoGenerated: true`.
* `comments` devuelve `comments`, cada uno con `commentId`, `parentId` (`null` en un comentario de primer nivel), `text`, `authorDisplayName`, `authorChannelId`, `authorProfileImageUrl`, `authorIsVerified`, `authorIsChannelOwner`, `isPinned`, `isHearted`, `likeCount`, `replyCount`, `publishedAt` y `updatedAt`. `totalCount` es el recuento que muestra YouTube, y `topLevelCount` y `replyCount` desglosan `returnedCount`.
* `channel` devuelve `channelId`, `title`, `handle`, `description`, `country`, `publishedAt`, `subscriberCount`, `videoCount`, `viewCount`, `isVerified`, `keywords`, `links`, `thumbnails`, `bannerUrl`, `rssUrl` y `uploadsPlaylistId`.
* `channel_videos` devuelve `videos` en el orden de `sort`, con el `channelId` y el `channelTitle` del canal.
* `transcript` devuelve el `text` de los subtítulos, los `segments` con tiempos (`start` y `duration` en segundos), el `language` leído y los `availableLanguages`. `truncated: true` marca una transcripción cortada en `maxSegments`.
* Un video con los me gusta ocultos lleva `likesHidden: true`, y uno con los comentarios desactivados lleva `commentsDisabled: true`. Un video solo para miembros lleva `membersOnly: true` y no tiene `viewCount`.
* Un video, canal o pista de subtítulos que no existe, o que requiere un espectador con sesión iniciada, como un video con restricción de edad, termina la tarea con `PAGE_UNAVAILABLE`. Los parámetros que no encajan entre sí la terminan con `BAD_PAYLOAD`. Solo se cobran las solicitudes completadas.

## Relacionado

* [Instagram](https://docs.querying.ai/es/engines/instagram.md)
* [Threads](https://docs.querying.ai/es/engines/threads.md)
* [Resumen de motores](https://docs.querying.ai/es/engines/overview.md)
* [Créditos y límites](https://docs.querying.ai/es/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.