> ## 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

> Search YouTube and read videos, comments, channels, channel uploads and transcripts as JSON, with views, likes, publish times, chapters and caption text.

Read public YouTube data as JSON through the async task API. Send `taskType` `SOCIAL` with `platform` `youtube`, and pick what to read with `action`. A completed request costs **0.5 credits**.

## Request

```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 } }'
```

Submit the task, then poll `GET /v1/async/task/{id}` or receive its webhook. See [Async tasks](https://docs.querying.ai/concepts/async-tasks.md).

## Actions

| `action` | Reads | Required |
| - | - | - |
| `search` (default) | YouTube search results | `query` |
| `recent` | The newest uploads for a query, newest first | `query` |
| `video` | One video's watch page | `videoId` |
| `comments` | A video's comments and their replies | `videoId` |
| `channel` | A channel's details and links | `channel` |
| `channel_videos` | A channel's videos, Shorts or live streams | `channel` |
| `transcript` | A video's captions | `videoId` |

`videoId` takes a video ID or a YouTube video URL (watch, `youtu.be`, Shorts or embed). `channel` takes a channel ID (`UC...`), an `@handle` or a channel URL.

## Parameters

`search` and `recent`:

* `query`: Required. The search query.
* `limit`: Optional integer from 1 to 50, default 10.
* `type`: `video` (default), `all`, `shorts`, `channel`, `playlist` or `movie`.
* `order`: `relevance` (default), `viewCount`, `date` or `rating`. `date` lists uploads newest first, like `recent`. `rating` sorts YouTube's most-viewed results by like count. `channel` and `playlist` searches take `relevance` or `viewCount`.
* `publishedAfter`: An ISO 8601 time, such as `2026-11-01T00:00:00Z`. Returns videos published after it.
* `videoDuration`: `short` (under 3 minutes), `medium` (3 to 20 minutes) or `long` (over 20 minutes).
* `features`: Any of `live`, `4k`, `hd`, `subtitles`, `creative_commons`, `360`, `vr180`, `3d`, `hdr`, `location` and `purchased`, as an array or a comma-separated string.
* `exactSpelling`: `true` searches the query as written, without YouTube's spelling correction.
* `pageToken`: The `nextPageToken` of the previous page. Video searches ordered by `relevance` or `viewCount` without `publishedAfter` return one, and each page skips every video the earlier pages returned.
* `regionCode` and `languageCode`: The YouTube region (`US`, `KR`, `JP`) and interface language (`en`, `ko`, `ja`) to search in.

`comments`:

* `limit`: Optional integer from 1 to 500, default 100. Replies count toward the limit.
* `order`: `relevance` (default, YouTube's top comments) or `time` (newest first).
* `includeReplies`: Optional, default `true`.

`channel_videos`:

* `tab`: `videos` (default), `shorts` or `streams`.
* `sort`: `latest` (default), `popular` or `oldest`.
* `limit`: Optional integer from 1 to 50, default 20.

`transcript`:

* `languages`: Caption languages in order of preference, such as `["en", "ko"]`. Without it, the video's default captions are read, then English, then the first track.
* `isGenerated`: `true` reads automatic captions only, `false` the uploader's captions only.
* `trackName`: The name of the caption track to read.
* `translateTo`: A language code. YouTube translates the captions into it.
* `maxSegments`: Optional integer from 1 to 5,000, default 2,000.

## Response example

```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"
}
```

## Result fields

* Every response echoes `platform` and `action`. Lists carry `returnedCount`.
* `search` and `recent` return `videos`. Each video has `position`, `videoId`, `url`, `title`, `description`, the channel's `channelId`, `channelTitle`, `channelHandle`, `channelUrl`, `channelThumbnail` and `channelIsVerified`, `publishedAt`, `publishedTimeText`, `duration` (ISO 8601), `durationSeconds`, `viewCount`, `likeCount`, `category`, `thumbnails`, `richThumbnail` (the moving preview), `badges` and `isFamilySafe`. A film adds `movie` with its poster, genre, year, cast and director.
* A search also returns the `channels`, `playlists`, `shorts` and `shelves` the results page shows, `totalResults` (YouTube's estimate), and `didYouMean` or `showingResultsFor` when YouTube corrects the query.
* `video` adds `tags`, `commentCount`, `subscriberCount`, `hasCaptions`, `chapters`, `mostReplayed`, `music`, `descriptionLinks` and `relatedVideos`. The uploader's chapters come first, and automatic chapters carry `autoGenerated: true`.
* `comments` returns `comments`, each with `commentId`, `parentId` (`null` on a top-level comment), `text`, `authorDisplayName`, `authorChannelId`, `authorProfileImageUrl`, `authorIsVerified`, `authorIsChannelOwner`, `isPinned`, `isHearted`, `likeCount`, `replyCount`, `publishedAt` and `updatedAt`. `totalCount` is the count YouTube shows, and `topLevelCount` and `replyCount` split `returnedCount`.
* `channel` returns `channelId`, `title`, `handle`, `description`, `country`, `publishedAt`, `subscriberCount`, `videoCount`, `viewCount`, `isVerified`, `keywords`, `links`, `thumbnails`, `bannerUrl`, `rssUrl` and `uploadsPlaylistId`.
* `channel_videos` returns `videos` in the order of `sort`, with the channel's `channelId` and `channelTitle`.
* `transcript` returns the caption `text`, timed `segments` (`start` and `duration` in seconds), the `language` read and the `availableLanguages`. `truncated: true` marks a transcript cut at `maxSegments`.
* A video with hidden likes carries `likesHidden: true`, and one with comments turned off carries `commentsDisabled: true`. A members-only video carries `membersOnly: true` and no `viewCount`.
* A video, channel or caption track that does not exist, or that needs a signed-in viewer such as an age-restricted video, ends the task with `PAGE_UNAVAILABLE`. Parameters that do not fit together end it with `BAD_PAYLOAD`. Only completed requests are charged.

## Related

* [Instagram](https://docs.querying.ai/engines/instagram.md)
* [Threads](https://docs.querying.ai/engines/threads.md)
* [Engine overview](https://docs.querying.ai/engines/overview.md)
* [Credits and limits](https://docs.querying.ai/concepts/credits-and-limits.md)


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