SignalYouTube · video
Read publicly available YouTube video or Short details. GET /api/v1/youtube/video accepts your x-api-key header. Production live requests are disabled pending source and commercial-use authorization, including cross-channel use.
Request parameters
Reads public video metadata embedded in the watch page, including the channel avatar, YouTube’s displayed subscriber and like labels, and listed caption languages when exposed. Like and subscriber totals may be rounded; the response does not invent exact counts from display labels. Caption track metadata does not include transcript text. This does not retrieve video bytes, transcripts, comments, sponsor segments, or private/age-restricted content. `language` asks YouTube for a localized page where available. The reference alias accepts `cache_max_age`; SignalShelf maps it to freshness and caps reusable cache age at seven days. The native route accepts `freshness`.
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Public YouTube watch, Shorts or youtu.be URL. Private, unlisted-only, age-gated and otherwise inaccessible videos are not extracted. |
language | string | No | Optional BCP-47 page language tag, for example en or hi. |
freshness | string | No | 24h (default), 1h, 7d, or live. Accepted cache hits are free; live forces refresh except simultaneous requests may share newly fetched data. |
Code examples
Set SIGNALSHELF_BASE_URL and SIGNALSHELF_API_KEY on your server.
curl "$SIGNALSHELF_BASE_URL/api/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D2reQut8WNGc" \
-H "x-api-key: $SIGNALSHELF_API_KEY"const response = await fetch(process.env.SIGNALSHELF_BASE_URL + "/api/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D2reQut8WNGc", {
headers: { 'x-api-key': process.env.SIGNALSHELF_API_KEY },
});
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
console.log(body.data, body.meta);import os, requests
response = requests.get(
os.environ['SIGNALSHELF_BASE_URL'] + "/api/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D2reQut8WNGc",
headers={'x-api-key': os.environ['SIGNALSHELF_API_KEY']},
timeout=30,
)
response.raise_for_status()
print(response.json())Response and pagination
The response contains public video_id, title, description, channel identifiers, duration, view count, thumbnail, publication date, category, live/unlisted flags, and extraction method when the watch page exposes them. Missing fields are null or omitted as documented. Video bytes, transcripts and sponsor details are not fetched. Comments and replies are available through separate public comment routes.
Video details are top-level fields under data, with the standard meta object beside them. Public watch-page fields vary. No media download, transcript, or sponsor extraction is included. Use the dedicated public comments and replies routes for comment data.
meta includes event_id, mode, cache, credits_charged, fetched_at, age_seconds, and duration_ms. A fresh successful result costs one credit; accepted cached results and failures cost zero.
Availability and failures
Implementation is not a continuous availability guarantee. Source rate limits, retention, deleted content, restrictions, and regional availability apply. This is an independent SignalShelf contract, not a drop-in competitor response format.
400: invalid parameters. 401: missing/revoked key. 402: insufficient credits. 404: missing public resource. 429: SignalShelf throttle. 502/503: upstream failure or rate limit, with credit restored.