YouTube Transcript API: Python SDK

The official Python SDK (getyoutubetranscript) for the GetYouTubeTranscript YouTube Transcript API. Get YouTube video transcripts, captions and subtitles (optionally with per-line timestamps) in Python without a Google API key, yt-dlp, or a headless browser. Get YouTube transcripts, search videos and channels, resolve channel handles, browse a channel's full upload history, search inside a channel, pull playlist contents, and check your credit balance, all with one typed client.

Install

pip install getyoutubetranscript

Requires Python 3.9+.

Quickstart

from getyoutubetranscript import Client

client = Client(api_key="sk_live_...")

transcript = client.get_transcript("https://www.youtube.com/watch?v=jNQXAC9IVRw")
print(transcript["title"], transcript["word_count"])
print(transcript["transcript"])

Getting an API key

Every request needs an API key. There are two ways to get one:

1. Dashboard - sign up at getyoutubetranscript.com. Free tier: 100 credits, no card required.
2. Self-serve, in code - use the signup/verify_signup helpers below. No key required for either call.

from getyoutubetranscript import signup, verify_signup

signup("you@example.com")          # sends a 6-digit code, valid 10 minutes
# ... read the code from your inbox ...
api_key = verify_signup("you@example.com", "123456")  # -> "sk_live_..."

The raw key is returned once by verify_signup and can't be retrieved again - store it yourself (env var, secret manager, etc).

Usage

Every method costs 1 credit unless noted "free" below. Failed and rate-limited requests are never charged. All methods raise GetYouTubeTranscriptError on failure - see Error handling.

Transcripts

client.get_transcript("jNQXAC9IVRw", language="en")

Pass timestamps=True to also get one entry per caption line in segments (same 1 credit). Without it, the response has no segments key.

result = client.get_transcript("5e37ZT3SQbk", timestamps=True)
print(result["segments"][0])
# {"start": 3.96, "duration": 4.56, "text": "So, Reed, education, which a lot of"}

Each segment is {"start", "duration", "text"} with start and duration in seconds. The Segment and TranscriptData typed dicts are importable from getyoutubetranscript.

Search

client.search("lofi beats", type="video", limit=10)

# Pagination
page2 = client.search(page_token=first_page["pagination"]["next_page_token"])

Channels

client.resolve_channel("@mkbhd")            # free - handle/URL -> channel ID
client.get_channel_latest("@mkbhd")         # free - metadata + latest uploads
client.search_channel("@mkbhd", "iphone")   # search within a channel
client.list_channel_videos("@mkbhd")        # full paginated upload history

# Pagination (search_channel and list_channel_videos both work the same way)
page = client.list_channel_videos("@mkbhd")
while page["has_more"]:
    page = client.list_channel_videos(continuation=page["continuation_token"])

Playlists

page = client.get_playlist("PLillGF-RfqbYE6Ik_EuXA2iZFcE082B3s")
while page["has_more"]:
    page = client.get_playlist(continuation=page["continuation_token"])

Account

client.get_credits()  # free - plan_credits_left, topup_credits_left, plan, rate_limit_per_minute

Error handling

Every non-2xx or {"success": false} response raises GetYouTubeTranscriptError with the API's parsed error shape:

from getyoutubetranscript import Client, GetYouTubeTranscriptError

client = Client(api_key="sk_live_...")

try:
    client.get_transcript("no-captions-here")
except GetYouTubeTranscriptError as e:
    print(e.code)          # e.g. "NOT_FOUND"
    print(e.message)       # human-readable message from the API
    print(e.status_code)   # 400 / 401 / 402 / 404 / 429 / 503, or 0 for a local network failure
    print(e.response_body) # full parsed error body, e.g. {"creditsLeft": 0} on PAYMENT_REQUIRED

Development

pip install -e ".[dev]"

# Unit tests - mocked HTTP, no network or API key needed, always safe to run
pytest tests -v --ignore=tests/live

# Live integration tests - hits the real API, spends credits, needs a key
GYT_API_KEY=sk_live_... pytest tests/live -v

Links

• Full API docs
• OpenAPI spec
• MCP server - if you want an AI agent to call this API directly instead of via Python

Related projects

Other ways to use the GetYouTubeTranscript API:

• youtube-transcript-api: YouTube Transcript API docs, endpoint reference, OpenAPI spec and examples in curl, Python, JavaScript, Go and PHP
• youtube-transcript-api-node: YouTube Transcript API SDK for Node.js / TypeScript
• youtube-mcp: Remote YouTube MCP server for Claude, ChatGPT, Cursor and VS Code
• youtube-transcript-skills: YouTube transcript Agent Skill for Claude Code, Cursor, Codex and OpenClaw
• youtube-transcript-cursor-plugin: YouTube Transcript Cursor plugin bundling the MCP server, skills, commands and a research agent
• n8n-nodes-getyoutubetranscript: YouTube transcript n8n community node, also usable as an AI Agent tool

License

MIT - see LICENSE.