YouTube Data
YouTube data access via TranscriptAPI.com — lightweight alternative to Google's YouTube Data API.
Setup
If $TRANSCRIPT_API_KEY is not set, read references/auth-setup.md [blocked] and follow the instructions there to get and store the key.
Required Headers
Every request needs two headers:
- Authorization:
Bearer $TRANSCRIPT_API_KEY - User-Agent: your agent's name and version if known (e.g.
HermesAgent/0.11.0,ClaudeCode/1.0). Version is optional — agent name alone is fine. Do not omit this header or send a bare default — Cloudflare will return a 403 (error code 1010) and block the request.
API Reference
Full OpenAPI spec: transcriptapi.com/openapi.json — consult this for the latest parameters and schemas.
Video Data (transcript + metadata) — 1 credit
Response:
Video Info & Rich Metadata
Check languages before spending a transcript credit (free), or pull view/like counts, publish date, description, duration, and tags (1 credit):
video/metadata returns title, viewCountText, likeCountText, publishDate, description, descriptionLinks, channel, thumbnails, plus details (duration, category, tags, caption tracks) and related videos when requested via include.
Naming:
/video/metadatawas previously/video/info. The old path still works but is deprecated.
Search Data — 1 credit/page
type also accepts playlist and movie. First page only, you can add sort (relevance/views), upload_date (hour/today/week/month/year), duration (short/medium/long), and features (e.g. hd,subtitles,cc).
Video result fields: videoId, title, channelId, channelTitle, channelHandle, channelVerified, lengthText, viewCountText, publishedTimeText, hasCaptions, thumbnails
Channel result fields (type=channel): channelId, title, handle, url, description, subscriberCount, verified, rssUrl, thumbnails
Channel Data
Channel endpoints accept channel — an @handle, channel URL, or UC... ID. No need to resolve first.
Resolve handle to ID (free):
Returns: {"channel_id": "UCsT0YIqwnpJCM-mx7-gSA4Q", "resolved_from": "@TED"}
Latest 15 videos with exact stats (free):
Returns: channel info, results array with videoId, title, published (ISO), viewCount (exact number), description, thumbnail
All channel videos (paginated, 1 credit/page):
Returns ~100 videos per page + continuation_token for pagination. tab also accepts shorts or streams, and you repeat the same tab when paginating.
Sorting. Add sort=latest, popular, or oldest to channel/videos to get a channel's videos in the order you want, for example its most-popular uploads first. A sorted page returns about 30 videos (an unsorted page returns about 100), and every page costs the same 1 credit.
When paging, send the same sort on each request.
Item fields. Every item carries members_only, true only when YouTube badges it "Members only", and those items have no viewCountText. tab=streams items carry lengthText and publishedTimeText (for example Streamed 2 years ago); tab=shorts returns null for both, because YouTube's Shorts grid publishes neither. On the channel-tab feeds (tab=videos with sort, tab=shorts, tab=streams) channelId, channelTitle, channelHandle and index are null.
Search within channel (1 credit):
Channel profile (1 credit):
Returns: title, handle, verified, subscriberCountText, videoCountText, description, tags, thumbnails, banners, availableTabs
Channel playlists (1 credit/page):
Returns: results (playlistId, title, url, videoCountText, thumbnails), continuation_token, has_more
Channel community posts (1 credit/page):
Returns: results (postId, authorName, text, publishedTimeText, voteCountText, attachment), continuation_token, has_more
Channel curated sections (1 credit):
Returns shelves of videos/playlists/shorts/featured channels, in the channel's own order. tab also accepts podcasts or releases.
Playlist Data — 1 credit/page
Accepts playlist — a YouTube playlist URL or playlist ID.
Returns: results (videos), playlist_info (title, numVideos, ownerName, viewCount), continuation_token, has_more
Credit Costs
Errors
Free tier: 100 credits, 300 req/min.
Copy-paste examples
Every request in this file as a ready-to-run one-liner: references/curl-examples.md [blocked]
