Get video

getVideo(id, query?, options?): Video

GET/v1/videos/{id}1 Credit

Two lookup depths share this path. mode=fast (default) reads the player response only: title, views, duration, thumbnails, caption languages, and basic channel attribution. Typically under a second, 1 credit.

mode=full also fetches the watch-next payload: like count, chapters, engagement heatmap, publish time, subscriber text, and channel avatar. 2 credits. Cache keys are separate, so a fast hit does not satisfy a full request.

Credits

Successful mode=fast responses deduct 1 credit. Successful mode=full responses deduct 2 credits. Failed lookups are not billed.

Security

API Token

The preferred authorization scheme for the YouTube Transcript API. Create a key with videos:read in the developer dashboard.

Example: Authorization: Bearer YOUR_API_KEY

See Authentication for scopes and rate limits.

Accepted permissions (at least one required)

videos:read

ParametersExpand Collapse

id:string

Path param:

11-character YouTube video ID.

mode?:string

Query param:

fast (default) or full.

required_country?:string

Query param:

ISO country hint used when region availability matters. Alias: country.

Returns (mode=fast)Expand Collapse

video_id:string

Echoed YouTube video ID.

title:string

Video title.

author:string

Channel display name. Same value as channel.title.

channel_id:string

Canonical channel ID. Same value as channel.id.

channel:object

Channel attribution from the player response.

id:string

Canonical channel ID.

title:string

Channel display name.

url:string

Channel URL.

description?:string

Player description / short description.

length_seconds:number

Duration in seconds.

view_count:number

View count at request time.

keywords?:string[]

Creator tags when the player returns them.

thumbnails?:Thumbnail[]

Player thumbnail ladder.

url:string

Image URL.

width:number

Width in pixels.

height:number

Height in pixels.

available_languages?:AvailableLanguage[]

Caption tracks advertised on the player. Present in both modes.

code:string

ISO language code, for example en.

name?:string

Player display name.

kind?:string

asr or manual.

variant?:string

Track variant when YouTube exposes one, for example gemini.

is_translatable?:boolean

Whether YouTube marks the track as translatable.

mode:string

Echoed lookup mode. fast in this response.

Returns (mode=full)Expand Collapse

All mode=fast fields, plus:

published?:number

Unix timestamp (seconds) for the upload / publish date.

like_count?:number

Like count from the watch page.

channel.subscribers?:string

Subscriber text from the watch page, for example 1.69M subscribers.

channel.avatar_url?:string

Best channel avatar URL from the watch page.

chapters?:Chapter[]

Timestamped chapters when YouTube exposes them (overlay, description, or pinned comment). Omitted when none exist.

title:string

Chapter title.

start_time_seconds:number

Start offset in seconds.

time_description?:string

Display timestamp, for example 0:00.

thumbnails?:Thumbnail[]

Chapter thumbnail ladder when present.

heatmap?:Heatmap

Most-replayed waveform from the watch page. Omitted when YouTube does not provide one.

markers:HeatmapMarker[]

Normalized intensity samples along the timeline (often ~100 points).

start_seconds:number

Sample start offset.

duration_seconds:number

Sample width.

intensity:number

Normalized 0.0–1.0.

peaks?:HeatmapPeak[]

High-intensity spans.

most_replayed?:HeatmapPeak

The single highest-intensity span, when labeled.

start_seconds:number

Span start.

end_seconds:number

Span end.

intensity:number

Normalized 0.0–1.0.

label?:string

For example Most replayed.

mode:string

full.

Full-mode responses keep every fast field. heatmap.markers is typically about 100 points; truncated:

{
  "video_id": "kCc8FmEb1nY",
  "title": "Let's build GPT: from scratch, in code, spelled out.",
  "author": "Andrej Karpathy",
  "channel_id": "UCXUPKJO5MZQN11PqgIvyuvQ",
  "channel": {
    "id": "UCXUPKJO5MZQN11PqgIvyuvQ",
    "title": "Andrej Karpathy",
    "url": "https://www.youtube.com/@AndrejKarpathy",
    "subscribers": "1.69M subscribers",
    "avatar_url": "https://yt3.ggpht.com/..."
  },
  "length_seconds": 6980,
  "view_count": 7850809,
  "published": 1673913600,
  "like_count": 169183,
  "chapters": [
    {
      "title": "intro: ChatGPT, Transformers, nanoGPT, Shakespeare",
      "start_time_seconds": 0,
      "time_description": "0:00"
    }
  ],
  "heatmap": {
    "markers": [
      { "start_seconds": 0, "duration_seconds": 69.8, "intensity": 0.12 },
      { "start_seconds": 1047, "duration_seconds": 69.8, "intensity": 1 }
    ],
    "peaks": [
      {
        "start_seconds": 1047,
        "end_seconds": 1465.8,
        "intensity": 1,
        "label": "Most replayed"
      }
    ],
    "most_replayed": {
      "start_seconds": 1047,
      "end_seconds": 1465.8,
      "intensity": 1,
      "label": "Most replayed"
    }
  },
  "mode": "full"
}

Get video

const id = "kCc8FmEb1nY";
const params = new URLSearchParams({ mode: "fast" });
const response = await fetch(
  `https://api.ytapi.dev/v1/videos/${id}?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.YT_API_KEY}`,
    },
  },
);

const video = await response.json();
console.log(video.title, video.view_count, video.mode);

import os
import requests

video_id = "kCc8FmEb1nY"
response = requests.get(
    f"https://api.ytapi.dev/v1/videos/{video_id}",
    headers={"Authorization": f"Bearer {os.environ['YT_API_KEY']}"},
    params={"mode": "full"},
)

video = response.json()
print(video["title"], video.get("like_count"))

curl -X GET "https://api.ytapi.dev/v1/videos/kCc8FmEb1nY?mode=fast" \
  -H "Authorization: Bearer $YT_API_KEY"

curl -X GET "https://api.ytapi.dev/v1/videos/kCc8FmEb1nY?mode=full" \
  -H "Authorization: Bearer $YT_API_KEY"

package main

import (
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.ytapi.dev/v1/videos/kCc8FmEb1nY?mode=fast", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("YT_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println(resp.Status)
}

200 example

{
  "video_id": "kCc8FmEb1nY",
  "title": "Let's build GPT: from scratch, in code, spelled out.",
  "author": "Andrej Karpathy",
  "channel_id": "UCXUPKJO5MZQN11PqgIvyuvQ",
  "channel": {
    "id": "UCXUPKJO5MZQN11PqgIvyuvQ",
    "title": "Andrej Karpathy",
    "url": "https://www.youtube.com/channel/UCXUPKJO5MZQN11PqgIvyuvQ"
  },
  "description": "We build a Generatively Pretrained Transformer (GPT)...",
  "length_seconds": 6980,
  "view_count": 7850809,
  "keywords": ["gpt", "transformer", "nanogpt"],
  "thumbnails": [
    {
      "url": "https://i.ytimg.com/vi/kCc8FmEb1nY/default.jpg",
      "width": 120,
      "height": 90
    }
  ],
  "available_languages": [
    {
      "code": "en",
      "name": "English (auto-generated)",
      "kind": "asr",
      "is_translatable": true
    }
  ],
  "mode": "fast"
}