Skip to main content
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

Submit the task, then poll GET /v1/async/task/{id} or receive its webhook. See Async tasks.

Actions

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

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.