SignalYouTube · video/transcript
Retrieve captions for a video owned by your connected YouTube channel. GET /api/v1/youtube/video/transcript accepts your x-api-key header. Production live requests are disabled pending source and commercial-use authorization, including cross-channel use.
Request parameters
Owner-only capability using YouTube Data API captions.list and captions.download. The video must belong to the channel connected to the same SignalShelf account, and that Google account must have permission to edit the video. It does not retrieve transcripts from arbitrary public videos or provide parity with public transcript services. Authorized data stays account-private and is retained for up to seven days. Google OAuth requests the broad youtube.force-ssl scope, which grants YouTube video, rating, comment and caption read/write/delete permissions.
| 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 | Return an exact available caption language, e.g. en or en-US. |
original_audio | boolean | No | Return captions matching the video’s identified original audio language; returns null without a match. Default: false. |
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/transcript?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/transcript?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/transcript?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 data and meta. data includes platform, resource, sample:false, provider, and the public source payload. Lists return data.items; individual resources return data.data.
Author feeds include data.next_cursor. Return it unchanged in cursor for the next page. Feed entries can include reposts. Single-post lookups resolve the handle to a DID first. Deleted or moderated posts may be unavailable.
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.