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.
Endpoint
Section titled “Endpoint”| Method | Path | Returns |
|---|---|---|
| POST | /api/v1/youtube/video |
Details of one YouTube video or Short |
Request & Response
Section titled “Request & Response”Request
Section titled “Request”| 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
urlorvideo_id. Both, or neither, is a400. - 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.
Response body
Section titled “Response body”| 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 |
The result object
Section titled “The result object”| 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.
Caching and cost
Section titled “Caching and cost”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.
Errors
Section titled “Errors”| 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 |
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"const params = new URLSearchParams({ video_id: "Y2Ah_DFr8cw", language: "en" });const res = await fetch(`https://api.megomi.my.id/api/v1/youtube/video?${params}`, { method: "POST", headers: { "x-api-key": process.env.MEGOMI_API_KEY }, signal: AbortSignal.timeout(60_000),});const data = await res.json();import requests
res = requests.post( "https://api.megomi.my.id/api/v1/youtube/video", params={"video_id": "Y2Ah_DFr8cw", "language": "en"}, headers={"x-api-key": "YOUR_API_KEY"}, timeout=60,)print(res.json())<?php$url = "https://api.megomi.my.id/api/v1/youtube/video?" . http_build_query(["video_id" => "Y2Ah_DFr8cw", "language" => "en"]);$ch = curl_init($url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);curl_setopt($ch, CURLOPT_TIMEOUT, 60);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);echo curl_exec($ch);q := url.Values{}q.Set("video_id", "Y2Ah_DFr8cw")q.Set("language", "en")req, _ := http.NewRequest("POST", "https://api.megomi.my.id/api/v1/youtube/video?"+q.Encode(), nil)req.Header.Set("x-api-key", "YOUR_API_KEY")client := &http.Client{Timeout: 60 * time.Second}resp, _ := client.Do(req){ "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}{ "status": 400, "title": "Bad Request", "detail": "url or video_id is required: send the video's address as url, or its 11-character id as video_id" }{ "status": 403, "title": "Forbidden", "detail": "this video is age-restricted, and YouTube shows its details only to a signed-in viewer; you were not charged", "requestId": "req_5mPq1XwK8jVcT4nR", "videoId": "Y2Ah_DFr8cw", "finishReason": "age-restricted"}{ "status": 404, "title": "Not Found", "detail": "the source reports no such video (deleted, or never existed); you were not charged. This answer is cached for an hour", "requestId": "req_5mPq1XwK8jVcT4nR", "finishReason": "not-found"}{ "status": 503, "title": "Service Unavailable", "detail": "no data fetched within 45s; you were not charged. The lookup is still running: submitting the same request again shortly may return it from cache, and is never charged twice", "requestId": "req_1qLr6PxV8nWtE3sJ", "finishReason": "no-data-fetched"}