Skip to content

YouTube Video Info

POST /api/v1/youtube/video — 1 credit per request

Look up a public YouTube video or Short. Returns the title, description and the links in it, view, like and comment counts, publish date, length, category, keywords, the channel and uploader, chapters, the replay heatmap, the shelves under the description, whether YouTube labels it as made with AI, the caption tracks it lists, and the videos YouTube suggests next. Videos and Shorts share one shape, and result.type says which. Send the video as a URL or an id, as query parameters.

Method Path Returns
POST /api/v1/youtube/video Details of one YouTube video or Short
Name Where Type Required Description
url query string (max 300) One of url and video_id A YouTube address: youtube.com, www.youtube.com, m.youtube.com, music.youtube.com or youtu.be, in one of the forms below. The scheme is optional. Other query parameters (t, list, si, …) are ignored
video_id query string (11) One of url and video_id The video id: letters, digits, - and _
language query string (2) No A two-letter code such as en, es or fr, case ignored. Sets the language of the text YouTube words itself (counts, dates, the AI notice). Default en
Address form Where it comes from
youtube.com/watch?v=<id> The browser’s address bar
youtu.be/<id> The app’s Share
youtube.com/shorts/<id> A Short
youtube.com/live/<id> A live stream
youtube.com/embed/<id> The embed frame
  • Send either url or video_id. Both, or neither, is a 400.
  • Only the video id is kept, so every form above of one video is one lookup, one cache entry and one charge.
  • A video asked for in two languages is two lookups, cached and charged apart.
  • A channel, playlist or any other address is a 400, as is a host other than the ones above or a port.
Field Type Description
requestId string Opaque ID for this request (req_…). Quote it when reporting a problem
videoId string The video’s id, resolved from whatever you sent
status string "success" on every 200
coalesced boolean true if this request joined a fetch of the same video and language that was already under way
cached boolean true if answered from a fetch of the last 15 minutes. Free if your key already paid for this video
result object The video, see below
finishReason string Empty on a freshly fetched answer, absent on a cached one. Ignore it on a 200
success boolean true on every 200
credits_charged integer What this request cost. 0 for a video and language your key already paid for
credits_remaining integer Your balance after this request
cached_at string UTC time of the cached answer. Present only on a cached answer
Field Type Description
id, url, thumbnail string The 11-character id, the canonical address (watch?v= for a video, /shorts/ for a Short) and a thumbnail link, which may expire
type string video or short
title string The title
description string or null null when the video has none
descriptionLinks array { url, text } for each link in the description, in order, with YouTube’s redirect wrapper removed
publishDate, publishDateText string or null As YouTube gives it (ISO 8601 with the uploader’s offset), and as it shows it in the language asked for
viewCountInt, likeCountInt, commentCountInt integer or null The exact counts. null when YouTube gave none, when the uploader hides likes, or when comments are off. A big video’s count shown rounded (1.2K) keeps its text and has no number
viewCountText, likeCountText, commentCountText string or null The same counts, as YouTube shows them
durationMs, durationFormatted integer, string The length to the second, and as HH:MM:SS
genre string or null YouTube’s category
keywords array The uploader’s keywords. Empty when none
channel object id, url, handle (without @, or null) and title of the channel the video is on
ownerByline object The owner under the player: channelId, name, url, subscriberCountText (null if hidden) and badges
uploader object channelId, author and url from the video’s metadata
chapters array { title, startMillis, thumbnail } in order. Empty when the video has none
most_replayed object or null The replay heatmap: markers (startMillis, durationMillis, intensityScoreNormalized from 0 to 1) and decorations. null when YouTube shows none, which is most videos
descriptionCards array The shelves under the description (people mentioned, music, games): title, subtitle and items. Empty when none
isMadeWithAI boolean YouTube labels the video as Made with AI or as altered or synthetic content
aiDisclosure string or null The text of YouTube’s How this was made notice, or another notice such as Auto-dubbed. null when there is none
captionTracks array The caption tracks the video lists: name.simpleText, vssId, languageCode, kind (asr for auto-generated, else null), isTranslatable and trackName. baseUrl is always null. Empty when none
watchNextVideos array The videos YouTube suggests next, in its order: id, title, thumbnail, channel, publishedTimeText, publishDateText, viewCountText, viewCountInt, lengthText, lengthInSeconds and videoUrl. Playlists and mixes are left out
collaborators, isPaidPromotion null Always null for now: no page checked showed either

Nothing is estimated. A field YouTube did not send is null (a list: []), never 0. A suggested video’s age (publishedTimeText) stays the relative text YouTube wrote (2 weeks ago), and its publishedTime and publishDate are always null.

Thumbnails and pictures are YouTube’s own and may stop working. Download what you need to keep.

A fresh answer is shared across keys for 15 minutes (1 hour for a video that does not exist), per video and language. Only a 200 is charged. Asking again for a video and language your key already paid for is free while it is cached, and resubmitting after a 503 never charges twice. A 403, 404, 429 or 503 is never charged.

Status When What to do
400 Neither or both of url and video_id, an address that is not a video, or a language that is not two letters Fix the request
401 No API key, or an unknown one Check your key
402 Your balance cannot cover this plus your unfinished lookups Buy credit
403 The video is age-restricted (finishReason age-restricted), or YouTube asked our service to sign in or refused the request (require-login, http-403, …) Not charged. An age-restricted video will not change on retry; for the other cases retry after the Retry-After delay
404 No such video, or one that was deleted (not-found) Not charged
429 Rate limit, too many unfinished lookups, or too many walls or videos that do not exist from this key (30 in 15 minutes by default) Slow down. Not charged
503 No answer in time, YouTube failing, the service paused after repeated refusals, or the endpoint switched off Not charged. Resubmit after the Retry-After delay
Terminal window
curl -X POST "https://api.megomi.my.id/api/v1/youtube/video?url=https://www.youtube.com/watch?v=Y2Ah_DFr8cw" \
-H "x-api-key: YOUR_API_KEY"
{
"requestId": "req_9f1kQ3zP7mLxA2dR",
"videoId": "Y2Ah_DFr8cw",
"status": "success",
"coalesced": false,
"cached": false,
"result": {
"id": "Y2Ah_DFr8cw",
"thumbnail": "https://i.ytimg.com/vi/Y2Ah_DFr8cw/hqdefault.jpg",
"url": "https://www.youtube.com/watch?v=Y2Ah_DFr8cw",
"publishDate": "2019-02-22T03:19:54-08:00",
"type": "video",
"title": "Inside the NBA: Chuck Trolls Jussie Smollett",
"description": null,
"descriptionLinks": [],
"commentCountText": "370",
"commentCountInt": 370,
"likeCountText": "4147",
"likeCountInt": 4147,
"viewCountText": "384,470 views",
"viewCountInt": 384470,
"publishDateText": "Feb 22, 2019",
"channel": {
"id": "UCWH3hing1Qb4LnkRfQdxsxQ",
"url": "https://www.youtube.com/@afroballer8906",
"handle": "afroballer8906",
"title": "Afroballer"
},
"chapters": [],
"watchNextVideos": [
{
"id": "62zSKE3G6I4",
"title": "Charles Barkley made Shaq walk off set",
"channel": { "title": "Chaz NBA", "handle": "ChazNBA" },
"publishedTimeText": "1 year ago",
"publishDate": null,
"viewCountText": "2.5 million views",
"viewCountInt": null,
"lengthText": "1:02",
"lengthInSeconds": 62,
"videoUrl": "https://www.youtube.com/watch?v=62zSKE3G6I4"
}
],
"keywords": [],
"genre": "People & Blogs",
"durationMs": 348000,
"durationFormatted": "00:05:48",
"isMadeWithAI": false,
"aiDisclosure": null,
"ownerByline": {
"channelId": "UCWH3hing1Qb4LnkRfQdxsxQ",
"name": "Afroballer",
"subscriberCountText": "1.01K subscribers",
"badges": []
},
"most_replayed": null,
"captionTracks": [
{
"baseUrl": null,
"name": { "simpleText": "English (auto-generated)" },
"vssId": "a.en",
"languageCode": "en",
"kind": "asr",
"isTranslatable": true
}
]
},
"finishReason": "",
"success": true,
"credits_charged": 1,
"credits_remaining": 249
}