Docs · Video details

Video details

A video's or Short's title, description, exact views and likes, publish date, length, tags, chapters and channel.

1 credit per callFresh within 1 hourMCP tool: youtube_video

GEThttps://api.lurkapi.com/v1/youtube/video

When to use this

Use it to track how a video performs or to pull its metadata: exact view and like counts, the full description and its links, tags, category, chapters, the "Most replayed" graph and the videos YouTube recommends next. Works for Shorts too (type: "short").

The comment count is rounded the way YouTube shows it; video comments returns the exact total. For what's said in the video, use video transcript.

Now and then YouTube's player doesn't answer. Then type, durationMs, durationFormatted, keywords, genre, publishDate, uploadDate, isFamilySafe and isUnlisted are null, and a non-English title and description may come back in YouTube's English translation. Everything else is still filled in.

Private, removed and unknown videos return 404 not_found.

Example request

Copy one and replace YOUR_API_KEY with your API key (get one free). The code versions read the key from the LURKAPI_API_KEY environment variable instead.

curl "https://api.lurkapi.com/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ" \
  -H "x-api-key: YOUR_API_KEY"

Paste it into a terminal, with your key in place of YOUR_API_KEY.

const params = new URLSearchParams({
  url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
});
const res = await fetch(`https://api.lurkapi.com/v1/youtube/video?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_API_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.descriptionLinks);

Node 18+. Save it as lurk.mjs and run node lurk.mjs. It reads your key from LURKAPI_API_KEY.

import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/youtube/video",
    params={
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    },
    headers={"x-api-key": os.environ["LURKAPI_API_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["descriptionLinks"])

Run pip install requests, save it as lurk.py and run python lurk.py. It reads your key from LURKAPI_API_KEY.

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"time"
)

func main() {
	params := url.Values{}
	params.Set("url", "https://www.youtube.com/watch?v=dQw4w9WgXcQ")
	req, _ := http.NewRequest("GET", "https://api.lurkapi.com/v1/youtube/video?"+params.Encode(), nil)
	req.Header.Set("x-api-key", os.Getenv("LURKAPI_API_KEY"))

	client := &http.Client{Timeout: 60 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		panic(err)
	}
	if data["success"] != true {
		panic(fmt.Sprintf("%v: %v", data["code"], data["error"]))
	}
	out, _ := json.MarshalIndent(data["descriptionLinks"], "", "  ")
	fmt.Println(string(out))
}

Save it as main.go and run go run main.go. It reads your key from LURKAPI_API_KEY.

<?php
$params = http_build_query([
    'url' => 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
]);
$context = stream_context_create(['http' => [
    'header' => 'x-api-key: ' . getenv('LURKAPI_API_KEY'),
    'timeout' => 60,
    'ignore_errors' => true,
]]);
$body = file_get_contents('https://api.lurkapi.com/v1/youtube/video?' . $params, false, $context);
$data = json_decode($body, true);
if (!$data['success']) {
    throw new Exception("{$data['code']}: {$data['error']}");
}
print_r($data['descriptionLinks']);

Save it as lurk.php and run php lurk.php. It reads your key from LURKAPI_API_KEY.

require 'json'
require 'net/http'

uri = URI('https://api.lurkapi.com/v1/youtube/video')
uri.query = URI.encode_www_form(
  'url' => 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
)
req = Net::HTTP::Get.new(uri)
req['x-api-key'] = ENV.fetch('LURKAPI_API_KEY')
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 60) do |http|
  http.request(req)
end
data = JSON.parse(res.body)
raise "#{data['code']}: #{data['error']}" unless data['success']
puts JSON.pretty_generate(data['descriptionLinks'])

Save it as lurk.rb and run ruby lurk.rb. It reads your key from LURKAPI_API_KEY.

Parameters

Add them to the URL after a ?. Join several with &.

Parameter	Description
`url` stringrequired	The video's URL (watch, youtu.be, /shorts/, /live/ or /embed/ links all work) or its 11-character id, e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ`. Example `https://www.youtube.com/watch?v=dQw4w9WgXcQ`

Example response

A real response, captured from the live API. Lists are trimmed to a couple of items, and long text such as media links is cut short with ….

Show the example response (5 KB)

{
  "success": true,
  "credits_remaining": 999986,
  "credits_charged": 1,
  "id": "dQw4w9WgXcQ",
  "type": "video",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "description": "The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever…",
  "descriptionLinks": [
    {
      "text": "https://linktr.ee/rickastleynever",
      "url": "https://linktr.ee/rickastleynever"
    },
    {
      "text": "https://RickAstley.lnk.to/YTSubID",
      "url": "https://RickAstley.lnk.to/YTSubID"
    },
    {
      "text": "https://RickAstley.lnk.to/FBFollowID",
      "url": "https://RickAstley.lnk.to/FBFollowID"
    },
    {
      "text": "https://RickAstley.lnk.to/TwitterID",
      "url": "https://RickAstley.lnk.to/TwitterID"
    },
    {
      "text": "https://RickAstley.lnk.to/InstagramID",
      "url": "https://RickAstley.lnk.to/InstagramID"
    },
    {
      "text": "https://RickAstley.lnk.to/storeID",
      "url": "https://RickAstley.lnk.to/storeID"
    },
    {
      "text": "https://RickAstley.lnk.to/TikTokID",
      "url": "https://RickAstley.lnk.to/TikTokID"
    },
    {
      "text": "https://RickAstley.lnk.to/SpotifyID",
      "url": "https://RickAstley.lnk.to/SpotifyID"
    },
    {
      "text": "https://RickAstley.lnk.to/AppleMusicID",
      "url": "https://RickAstley.lnk.to/AppleMusicID"
    },
    {
      "text": "https://RickAstley.lnk.to/AmazonMusicID",
      "url": "https://RickAstley.lnk.to/AmazonMusicID"
    },
    {
      "text": "https://RickAstley.lnk.to/DeezerID",
      "url": "https://RickAstley.lnk.to/DeezerID"
    }
  ],
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "viewCountText": "1,821,634,661 views",
  "viewCountInt": 1821634661,
  "likeCountText": "19M",
  "likeCountInt": 19439173,
  "commentCountText": "2.4M",
  "commentCountInt": 2400000,
  "publishDate": "2009-10-24T23:57:33-07:00",
  "uploadDate": "2009-10-24T23:57:33-07:00",
  "publishDateText": "Oct 24, 2009",
  "channel": {
    "id": "UCuAXFkgsw1L7xaCfnd5JJOw",
    "url": "https://www.youtube.com/@RickAstleyYT",
    "handle": "RickAstleyYT",
    "title": "Rick Astley",
    "subscriberCountText": "4.55M subscribers",
    "subscriberCount": 4550000,
    "isVerified": true,
    "avatar": "https://yt3.ggpht.com/_ShEGOdg-t5YGJse14Ooq6FYBZqX_QSlhaTNjG06miYusm5lWm…"
  },
  "chapters": [],
  "keywords": [
    "rick astley",
    "Never Gonna Give You Up",
    "nggyu",
    "never gonna give you up lyrics",
    "rick rolled",
    "Rick Roll",
    "rick astley official",
    "rickrolled",
    "Fortnite song",
    "Fortnite event",
    "Fortnite dance",
    "fortnite never gonna give you up",
    "rick roll",
    "rickrolling",
    "rick rolling",
    "never gonna give you up",
    "80s music",
    "rick astley new",
    "animated video",
    "rickroll",
    "meme songs",
    "never gonna give u up lyrics",
    "Rick Astley 2022",
    "never gonna let you down",
    "animated",
    "rick rolls 2022",
    "never gonna give you up karaoke"
  ],
  "genre": "Music",
  "durationMs": 213000,
  "durationFormatted": "00:03:33",
  "isFamilySafe": true,
  "isUnlisted": false,
  "most_replayed": {
    "markers": [
      {
        "startMillis": 0,
        "durationMillis": 2140,
        "intensityScoreNormalized": 1
      },
      {
        "startMillis": 2140,
        "durationMillis": 2140,
        "intensityScoreNormalized": 0.4217676376522385
      }
    ],
    "ranges": [
      {
        "visibleTimeRangeStartMillis": 0,
        "visibleTimeRangeEndMillis": 6420,
        "decorationTimeMillis": 2140,
        "label": "Most replayed"
      }
    ]
  },
  "watchNextVideos": [
    {
      "id": "NWItxGY5NNk",
      "title": "80'S MUSIC ON THE ROAD | 2 Hours of Classic '80s Hits",
      "thumbnail": "https://i.ytimg.com/vi/NWItxGY5NNk/hqdefault.jpg?sqp=-oaymwEcCNACELwBSFX…",
      "channel": {
        "id": "UCkUSPjRL8md2hlE8bNXAT-A",
        "url": "https://www.youtube.com/@everysongisascar",
        "handle": "everysongisascar",
        "title": "every song is a scar"
      },
      "publishedTimeText": "3 months ago",
      "viewCountText": "3.9M",
      "viewCountInt": 3900000,
      "lengthText": "2:16:49",
      "lengthInSeconds": 8209,
      "videoUrl": "https://www.youtube.com/watch?v=NWItxGY5NNk"
    },
    {
      "id": "yPYZpwSpKmA",
      "title": "Rick Astley - Together Forever (Official Video) [4K Remaster]",
      "thumbnail": "https://i.ytimg.com/vi/yPYZpwSpKmA/hqdefault.jpg?sqp=-oaymwEcCNACELwBSFX…",
      "channel": {
        "id": "UCuAXFkgsw1L7xaCfnd5JJOw",
        "url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
        "handle": null,
        "title": "Rick Astley"
      },
      "publishedTimeText": "16 years ago",
      "viewCountText": "206M",
      "viewCountInt": 206000000,
      "lengthText": "3:24",
      "lengthInSeconds": 204,
      "videoUrl": "https://www.youtube.com/watch?v=yPYZpwSpKmA"
    }
  ]
}

Response fields

Every field in a successful response, and what it means. A name with [] belongs to each item of a list: descriptionLinks[].text is the text of every item in descriptionLinks. null means there's no value.

Show all 65 fields

Field	Type	Description
success	true	Always true here; errors have `success: false`.
credits_remaining	number	Your balance after this call. On anonymous playground calls: free tries left today.
credits_charged	number	Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1).
id	string	Video id, e.g. `dQw4w9WgXcQ`.
type	stringcan be null	`short` for YouTube Shorts, else `video`. null in the rare case the player details were unavailable (see `durationMs`).
url	string	Canonical link: /shorts/<id> for Shorts, /watch?v=<id> otherwise.
title	string	Video title, as the creator wrote it (not YouTube's English translation).
description	string	Full description as the creator wrote it, plain text, links in full.
descriptionLinks	object[]	Links in the description, in order: websites and other YouTube videos (not hashtags, mentions or timestamps).
descriptionLinks[].text	string	The link as it appears in the description; the full URL where YouTube shows a chip or shortens it.
descriptionLinks[].url	string	Where it goes (YouTube's redirect wrapper removed).
thumbnail	string	Largest thumbnail URL.
viewCountText	stringcan be null	Views as YouTube shows them, e.g. "1,821,613,271 views", or "8,698 watching now" during a live stream.
viewCountInt	numbercan be null	Exact view count (total views, also during a live stream).
likeCountText	stringcan be null	Likes as YouTube shows them, e.g. "19M"; null when the creator hides likes.
likeCountInt	numbercan be null	Exact like count. null when the creator hides likes.
commentCountText	stringcan be null	Comments as YouTube shows them, e.g. "2.4M"; null when comments are off.
commentCountInt	numbercan be null	Comment count from that text, so rounded above 1,000 (2.4M → 2400000). The comments endpoint returns the exact total.
publishDate	stringcan be null	Published at, ISO 8601 with YouTube's offset, e.g. `2009-10-24T23:57:33-07:00`. null if unavailable.
uploadDate	stringcan be null	Uploaded at, ISO 8601 (differs from publishDate for scheduled videos and premieres). null if unavailable.
publishDateText	stringcan be null	The date line under the video, e.g. "Oct 24, 2009" or "Premiered 3 hours ago".
channel	object	The channel that posted it.
channel.id	stringcan be null	Channel id, `UC…`.
channel.url	stringcan be null	Channel page, e.g. `https://www.youtube.com/@RickAstleyYT`.
channel.handle	stringcan be null	Handle without the @, e.g. `RickAstleyYT`; null if YouTube shows none.
channel.title	stringcan be null	Channel name.
channel.subscriberCountText	stringcan be null	Subscribers as YouTube shows them, e.g. "4.55M subscribers".
channel.subscriberCount	numbercan be null	Subscribers as a number, from that rounded text (4.55M → 4550000).
channel.isVerified	boolean	Has a verified or official artist badge.
channel.avatar	stringcan be null	Channel avatar URL.
chapters	object[]	Chapters from the description (or YouTube's automatic ones), in order. Empty if the video has none.
chapters[].title	string	Chapter title.
chapters[].startMs	number	Where the chapter starts, in milliseconds from the start of the video.
chapters[].thumbnail	stringcan be null	Chapter thumbnail URL.
keywords	string[]can be null	The creator's tags. null if unavailable.
genre	stringcan be null	YouTube category, e.g. "Music" or "Education". null if unavailable.
durationMs	numbercan be null	Length in milliseconds. null during a live stream, and if unavailable. This and the other fields marked "if unavailable" come from YouTube's player, which now and then doesn't answer. The rest of the response is still complete then.
durationFormatted	stringcan be null	Length as `HH:MM:SS`, e.g. "00:03:33". null during a live stream or if unavailable.
isFamilySafe	booleancan be null	YouTube considers it family safe. null if unavailable.
isUnlisted	booleancan be null	Unlisted (only people with the link can find it). null if unavailable.
most_replayed	objectcan be null	The "Most replayed" graph. null when YouTube doesn't show one (newer or less-watched videos).
most_replayed.markers	object[]	The replay graph over the timeline, usually 100 equal slices.
most_replayed.markers[].startMillis	number	Start of this slice of the video, in milliseconds.
most_replayed.markers[].durationMillis	number	Length of the slice, in milliseconds.
most_replayed.markers[].intensityScoreNormalized	number	How often this slice is replayed, 0–1 (1 = the most replayed slice).
most_replayed.ranges	object[]	Ranges YouTube highlights as most replayed.
most_replayed.ranges[].visibleTimeRangeStartMillis	number	Start of the highlighted range, in milliseconds.
most_replayed.ranges[].visibleTimeRangeEndMillis	number	End of the highlighted range, in milliseconds.
most_replayed.ranges[].decorationTimeMillis	number	The peak YouTube points at, in milliseconds.
most_replayed.ranges[].label	stringcan be null	YouTube's label, e.g. "Most replayed".
watchNextVideos	object[]	The "Up next" videos YouTube recommends beside this one (videos only, no mixes or playlists).
watchNextVideos[].id	string	Video id.
watchNextVideos[].title	stringcan be null	Video title (YouTube may translate non-English titles into English).
watchNextVideos[].thumbnail	stringcan be null	Thumbnail URL.
watchNextVideos[].channel	object	The channel that posted it.
watchNextVideos[].channel.id	stringcan be null	Channel id, `UC…`.
watchNextVideos[].channel.url	stringcan be null	Channel page, e.g. `https://www.youtube.com/@RickAstleyYT`.
watchNextVideos[].channel.handle	stringcan be null	Handle without the @, e.g. `RickAstleyYT`; null if YouTube shows none.
watchNextVideos[].channel.title	stringcan be null	Channel name.
watchNextVideos[].publishedTimeText	stringcan be null	When it was posted, relative, e.g. "3 months ago".
watchNextVideos[].viewCountText	stringcan be null	Views as YouTube shows them, e.g. "3.9M".
watchNextVideos[].viewCountInt	numbercan be null	Views from that rounded text (3.9M → 3900000).
watchNextVideos[].lengthText	stringcan be null	Length as shown on the thumbnail, e.g. "4:05".
watchNextVideos[].lengthInSeconds	numbercan be null	Length in seconds.
watchNextVideos[].videoUrl	string	Link to the video.

Cost and freshness

Each call costs 1 credit. Calls turned away before they reach the platform (invalid parameters, a key or balance problem, a rate limit) are free, and so are 5xx errors. A not_found is charged, since the platform was checked. How charging works.

Answers are cached for up to 1 hour. A repeat call within that time can return the same data, and costs the same.

Errors

A failed call returns success: false, an error message, a code your program can check, and a docs link. These are the errors this endpoint can return. All error codes.

Status	Code	Meaning
401	`missing_api_key`	No API key was sent. Put it in the `x-api-key` header.
401	`invalid_api_key`	This key doesn't exist or was revoked.
402	`insufficient_credits`	Not enough credits for this call. Buy a pack, or wait for tomorrow's free top-up.
402	`over_max_credits`	This call would cost more than the `max_credits` you set. The error says what it needs; raise `max_credits` to allow it. Not charged.
403	`account_suspended`	This account is suspended. Email support@lurkapi.com. Not charged.
404	`not_found`	What you asked for (a post, an ad, a subreddit) doesn't exist, or there's no endpoint at that path. Charged if the platform was checked.
405	`method_not_allowed`	Endpoints only take `GET`, with parameters in the URL.
429	`rate_limited`	Too many calls in a short time. Wait as many seconds as the `retry-after` header says, then retry.
500	`internal_error`	Something broke on our side. Retry. Not charged.
502	`upstream_error`	The platform didn't send a usable answer. Retry. Not charged.
503	`upstream_busy`	All our connections to the platform are busy. Retry in a few seconds. Not charged.
504	`upstream_timeout`	The platform took over 30 seconds to answer (90 for web pages). Retry. Not charged.

Use it in Claude

Connect LurkAPI to Claude and ask in plain English. This endpoint is the youtube_video tool. For example:

Ask Claude

Use LurkAPI's youtube_video tool with url "https://www.youtube.com/watch?v=dQw4w9WgXcQ", then summarize what you find.

Claude calls youtube_video with arguments like these, and each call costs 1 credit:

Tool arguments

{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}

To save tokens, tool results leave out empty fields, keep one URL per image or video, and give transcripts as plain text unless you pass timestamps=true. A result over 45,000 characters comes in parts. Its _note gives the offset for the next part, and later parts are free for 15 minutes. Pass trim=false for the full response.

From the blog

All posts