Reference

Data types

What the information looks like when it comes back. Each field is listed with its type: text, a number, yes or no, or a list. Anything we could not check yet is labelled, and the Words explained page defines the terms.

VideoResult VideoStats LiveStreamInfo ChannelMetadata TranscriptEntry SearchResponse

VideoResult

Observed · 18 fields

Returned by /, /shorts, /trending, /channel/:id, /playlist/:id (as an array) and /video/:id (as one object). The same fields in every language SDK.

Field	Type	Example / notes
id	string	11-character video ID, e.g. dQw4w9WgXcQ
title	string	Video title
author	string	Channel name
channelUrl	string	Sometimes relative, e.g. /@petcollective. Prefix with https://www.youtube.com.
thumbnail	string	Main thumbnail URL. May be empty.
thumbnails	array	[{ url, width, height }], several qualities
fullUrl	string	https://www.youtube.com/watch?v=ID
embedUrl	string	https://www.youtube.com/embed/ID?rel=0
duration	string	Display text, e.g. "3:33" or "1:00:17"
durationSeconds	number	Use this for math. e.g. 213
viewCount	string	Display text, e.g. "1,824,726,106 views"
viewCountRaw	number	Use this for sorting. e.g. 1824726106
publishedTime	string	Relative text, e.g. "1y ago". May be empty.
description	string	Beginning of the description (about 200 characters)
channelAvatar	string	Channel picture URL. May be empty.
isLive	boolean	true while the stream is live in search and channel results. Always false from /video/:id, because the worker never sets it. Use /video/:id/live.
isUpcoming	boolean	true for upcoming streams in search results. Unreliable on /live (see the note there). Always false from /video/:id.
isVerified	boolean	Verified channel badge

VideoStats

Observed

From /video/:id/stats. Counts are rounded: dQw4w9WgXcQ returned views: 1800000000 on 9 Oct 2026, so treat them as approximate. comments is always 0, because the worker hard-codes it.

Field	Type
views	number
likes	number \| null
comments	number (always 0)
isLive	boolean
viewerCount	number \| null

LiveStreamInfo

Observed

From /video/:id/live. Known issue: the worker sets isUpcoming to true whenever a video is not live and has zero viewers. An ordinary video such as dQw4w9WgXcQ therefore returns true. Check isLive and scheduledStartTime together.

Field	Type
isLive	boolean
isUpcoming	boolean
viewerCount	number
viewerCountStr	string
startTime	string
scheduledStartTime	string
likesCount	number
dislikesCount	number

ChannelMetadata

Observed · some fields empty

From /channel/:id/metadata. In our test, name and subscriber fields were empty for the sample channel, so treat each field as optional.

Field	Type	Notes
id	string	Channel ID, starts with UC
name	string	Display name
handle	string	e.g. @handle
description	string	Channel description
subscriberCount	string	Display text
subscriberCountRaw	number	Numeric count, may be 0
videoCount	string	Display text
videoCountRaw	number	Numeric count, may be 0
avatar	string	Profile image URL
banner	string	Banner image URL
isVerified	boolean	Verified badge
socialLinks	array	Links from the channel About section
url	string	Channel URL

TranscriptEntry

From worker source · not yet seen live

Array item from /video/:id/transcript. The endpoint was empty in our tests, so confirm these fields on a video that has captions.

Field	Type
text	string
start	number · seconds
duration	number · seconds

SearchResponse

SDK only

The TypeScript SDK wraps results in this object. The HTTP API returns a bare array instead.

Field	Type
results	VideoResult[]
continuation	string \| null
apiKey	string
context	object

Python returns a list of VideoResult objects from search(), and a SearchResponse from search_continue().

Health

From /health

object

{ "status": "ok", "version": "2.0.0" }

Error

Any 4xx or 5xx response

object

{ "error": "Missing query param \"q\"" }

Comment & related

Both shapes come from the worker source. Neither endpoint returned data in our tests, so check a live response before you rely on them. The full field lists are on the Endpoints page.

Writing type-safe code

Here is a TypeScript type that matches the observed VideoResult. Paste it into your project and extend it as you need.

types.ts

export interface VideoResult {
  id: string;
  title: string;
  author: string;
  channelUrl: string;
  thumbnail: string;
  thumbnails: { url: string; width: number; height: number }[];
  fullUrl: string;
  embedUrl: string;
  duration: string;
  durationSeconds: number;
  viewCount: string;
  viewCountRaw: number;
  publishedTime: string;
  description: string;
  channelAvatar: string;
  isLive: boolean;
  isUpcoming: boolean;
  isVerified: boolean;
}

export interface VideoStats {
  views: number;
  likes: number | null;
  comments: number | null;
  isLive: boolean;
  viewerCount: number | null;
}