YouTube Metadata API: Title, Duration and Availability Before You Download (2026)

A user pastes a YouTube link into your app. Before you spend bandwidth and time downloading it, you want to show them what they're about to import: the title, how long it is, whether it's in their language, and whether it will download at all.

That's a metadata lookup, and it shouldn't need a full download or a YouTube Data API project with its own quota.

Short version: call POST /info with the video URL. You get back the title, the duration in seconds and, when the video is region-locked, the countries where it plays. Add includeAudioTracks: true to also list its audio languages. Metadata lookups use no bandwidth, and failures aren't charged. If you're going to download anyway, POST /download returns the title and duration in its first response, before the file is ready.

What the metadata endpoint returns

{
  "jobId": "6f9c1234-5e8a-4b2f-9c1e-0a7b69cfc45e",
  "status": "success",
  "result": {
    "title": "Rick Astley - Never Gonna Give You Up",
    "duration": 213,
    "url": "https://youtu.be/dQw4w9WgXcQ"
  }
}

Get a video's metadata

The call is a short job: submit it, then read the result a moment later.

# 1. Submit
curl -X POST https://vidkraken.com/api/v2/info \
-H "Authorization: Bearer $VIDKRAKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://youtu.be/dQw4w9WgXcQ"}'
# {"jobId": "6f9c1234-...", "status": "pending"}

# 2. Read the result
curl https://vidkraken.com/api/v2/info/6f9c1234-... \
-H "Authorization: Bearer $VIDKRAKEN_API_KEY"

import os, time, requests

API = "https://vidkraken.com/api/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['VIDKRAKEN_API_KEY']}"}

def video_info(url, audio_tracks=False):
  job = requests.post(f"{API}/info", headers=HEADERS,
                      json={"url": url, "includeAudioTracks": audio_tracks}).json()
  while True:
      status = requests.get(f"{API}/info/{job['jobId']}", headers=HEADERS).json()
      if status["status"] == "success":
          return status["result"]
      if status["status"] == "failed":
          raise RuntimeError(status.get("errorCode") or status["error"])
      time.sleep(1)

info = video_info("https://youtu.be/dQw4w9WgXcQ")
print(info["title"], info["duration"])

const API = "https://vidkraken.com/api/v2";
const headers = {
Authorization: "Bearer " + process.env.VIDKRAKEN_API_KEY,
"Content-Type": "application/json",
};

async function videoInfo(url, includeAudioTracks = false) {
const job = await fetch(API + "/info", {
  method: "POST",
  headers,
  body: JSON.stringify({ url, includeAudioTracks }),
}).then((r) => r.json());

while (true) {
  const s = await fetch(API + "/info/" + job.jobId, { headers }).then((r) => r.json());
  if (s.status === "success") return s.result;
  if (s.status === "failed") throw new Error(s.errorCode ?? s.error);
  await new Promise((r) => setTimeout(r, 1000));
}
}

const info = await videoInfo("https://youtu.be/dQw4w9WgXcQ");
console.log(info.title, info.duration);

Results are kept for an hour after you submit, so read them within that window. Accepted URL shapes are youtube.com/watch?v=, youtu.be/ and youtube.com/live/.

Check a video will download before you queue it

Most failed imports can be caught at the metadata step, before the user waits on anything:

MAX_SECONDS = 2 * 60 * 60  # your own limit
DOWNLOADABLE_FROM = {"US", "DE", "GB"}  # example

def check(url):
    try:
        info = video_info(url)
    except RuntimeError as e:
        # VIDEO_NOT_FOUND, PRIVATE_VIDEO, AGE_RESTRICTED, ...
        return f"Can't import this video: {e}"

    if info["duration"] > MAX_SECONDS:
        return "This video is longer than 2 hours."

    region = info.get("regionRestriction")
    if region and "allowed" in region and not DOWNLOADABLE_FROM & set(region["allowed"]):
        return "This video is region-locked."

    return None  # good to go

A failed lookup carries the same errorCode values as a failed download, such as VIDEO_NOT_FOUND, PRIVATE_VIDEO or LIVE_STREAM_IN_PROGRESS. The error codes guide lists every one with a message you can show your users.

You don't need to check which resolutions a video has. Ask for the quality you want, for example 1080. If the video doesn't go that high, you get the best quality below it, and the finished download's actualFormat tells you what was delivered.

Metadata and a download in one step

If you're going to download the video anyway, skip the separate lookup. POST /download returns the title and duration in its first response, while the file is still being prepared:

{
  "jobId": "69cfc45e8a3b4d2f9c1e0a7b",
  "title": "Rick Astley - Never Gonna Give You Up",
  "duration": 213,
  "status": "IN_QUEUE"
}

Show the title in your UI straight away, then deliver the file when the job finishes. The completed job adds downloadUrl and fileSize. See the YouTube download API guide for the full flow.

Common uses

• Import previews. Show the title and length as soon as a user pastes a link.
• Limits and pricing. Refuse or price videos by duration before anything is downloaded.
• Language pickers. List dubbed audio tracks and let the user choose. See multi-language audio tracks.
• AI and media pipelines. Filter a batch of URLs by length and availability before spending bandwidth on them.
• Trimming. Validate startTime and endTime against the real duration before you request a clip.

What it doesn't return

/info is built to answer "should I download this?" quickly. It doesn't return view counts, likes, descriptions, tags or channel statistics. For those, use the official YouTube Data API, which is free within its daily quota and has those fields. It can't download videos, though. Here's why.

For a thumbnail, YouTube serves one at a predictable address: https://i.ytimg.com/vi/VIDEO_ID/hqdefault.jpg.

Cost

A metadata lookup counts against your plan's info quota only when it succeeds, and uses no bandwidth. Plans include far more lookups than downloads, so in practice bandwidth runs out first. Reading results is free, and so are failures. See pricing.

Frequently asked questions