youtube-full

YouTube Full

Complete YouTube toolkit via TranscriptAPI.com ↗. Everything in one skill.

Setup

If $TRANSCRIPT_API_KEY is not set, read references/auth-setup.md ↗ 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.

Transcript — 1 credit

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_URL&format=text&include_timestamp=true&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

| Param | Required | Default | Values |

| ------------------- | -------- | ------- | ------------------------------- |

| video_url | yes | — | YouTube URL or 11-char video ID |

| format | no | json | json, text |

| include_timestamp | no | true | true, false |

| send_metadata | no | false | true, false |

Response (format=json):

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [{ "text": "...", "start": 18.0, "duration": 3.5 }],
  "metadata": { "title": "...", "author_name": "...", "author_url": "..." }
}

Video Info & Metadata

# Free — languages available for the transcript endpoint
GET https://transcriptapi.com/api/v2/youtube/info?video_url=VIDEO_URL
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

# 1 credit — rich metadata (views, likes, description, duration, tags)
GET https://transcriptapi.com/api/v2/youtube/video/metadata?video_url=VIDEO_URL&include=details,related
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

include on video/metadata accepts details and/or related. Naming: /video/metadata was previously /video/info — the old path still works but is deprecated.

Search — 1 credit/page

# Videos
GET https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=20
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

# Channels, playlists, or movies
GET https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=channel&limit=10
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

| Param | Required | Default | Validation |

| ------- | -------- | ------- | ----------------------------------------------- |

| q | yes | — | 1-200 chars |

| type | no | video | video, channel, playlist, movie |

| sort | no | relevance | relevance, views (first page only) |

| upload_date | no | — | hour, today, week, month, year (videos, first page) |

| duration | no | — | short, medium, long (videos, first page) |

| features | no | — | e.g. hd,subtitles,cc (first page) |

| limit | no | 20 | 1-50 |

Channels

All channel endpoints accept channel — an @handle, channel URL, or UC... channel ID. No need to resolve first.

Resolve handle — FREE

GET https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Response: {"channel_id": "UC...", "resolved_from": "@TED"}

Latest 15 videos — FREE

GET https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Returns exact viewCount and ISO published timestamps.

Channel feed (videos/shorts/streams) — 1 credit/page

# First page (100 items, tab defaults to "videos")
GET https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA&tab=videos
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

# Most-viewed first (channel Videos tab, ~30 items)
GET https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA&sort=popular
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

# Next pages (repeat the same tab AND sort)
GET https://transcriptapi.com/api/v2/youtube/channel/videos?continuation=TOKEN&sort=popular
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Provide exactly one of channel or continuation. tab is videos (default), shorts, or streams. Response includes continuation_token and has_more.

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

GET https://transcriptapi.com/api/v2/youtube/channel/search?channel=@TED&q=QUERY&limit=30
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Channel profile — 1 credit

GET https://transcriptapi.com/api/v2/youtube/channel/info?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Returns title, handle, verified flag, subscriber/video counts, description, tags, thumbnails, banners, and availableTabs.

Channel playlists — 1 credit/page

GET https://transcriptapi.com/api/v2/youtube/channel/playlists?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Returns each playlist's playlistId, title, url, videoCountText — feed a playlistId into the Playlists endpoint below.

Channel community posts — 1 credit/page

GET https://transcriptapi.com/api/v2/youtube/channel/posts?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Channel curated sections — 1 credit

GET https://transcriptapi.com/api/v2/youtube/channel/sections?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

tab is featured (default, Home page), podcasts, or releases.

Playlists — 1 credit/page

Accepts playlist — a YouTube playlist URL or playlist ID.

# First page
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist=PL_ID
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

# Next pages
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?continuation=TOKEN
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Valid ID prefixes: PL, UU, LL, FL, OL. Response includes playlist_info, results, continuation_token, has_more.

Credit Costs

| Endpoint | Cost |

| ----------------- | -------- |

| transcript | 1 |

| info | free |

| video/metadata | 1 |

| search | 1/page |

| channel/resolve | free |

| channel/info | 1 |

| channel/latest | free |

| channel/videos | 1/page |

| channel/search | 1 |

| channel/playlists | 1/page |

| channel/posts | 1/page |

| channel/sections | 1 |

| playlist/videos | 1/page |

Validation Rules

| Field | Rule |

| ---------- | ------------------------------------------------------- |

| channel | @handle, channel URL, or UC... ID |

| playlist | Playlist URL or ID (PL/UU/LL/FL/OL prefix) |

| q | 1-200 chars |

| type (search) | video (default), channel, playlist, movie |

| tab (channel/videos) | videos (default), shorts, streams |

| sort (channel/videos) | latest, popular, oldest (omit for the uploads feed) |

| tab (channel/sections) | featured (default), podcasts, releases |

| include (video/metadata) | details, related (comma-separated) |

| limit | 1-50 |

Errors

| Code | Meaning | Action |

| -------- | ---------------- | ---------------------------------------------- |

| 401 | Bad API key | Check key |

| 402 | No credits | transcriptapi.com/billing |

| 403/1010 | Cloudflare block | Add or fix User-Agent header |

| 404 | Not found | Resource doesn't exist or no captions |

| 408 | Timeout | Retry once after 2s |

| 422 | Validation error | Check param format |

| 429 | Rate limited | Wait, respect Retry-After |

Typical Workflows

Research workflow: search → pick videos → fetch transcripts

# 1. Search
GET https://transcriptapi.com/api/v2/youtube/search?q=machine+learning+explained&limit=5
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

# 2. Transcript
GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Channel monitoring: latest (free) → transcript

# 1. Latest uploads (free — pass @handle directly)
GET https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

# 2. Transcript of latest
GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

Free tier: 100 credits, 300 req/min. Starter ($5/mo): 1,000 credits.

Copy-paste examples

Every request in this file as a ready-to-run one-liner: references/curl-examples.md ↗