Official SDKs
Type-safe clients for Python and TypeScript. Zero boilerplate, built-in error handling, and full API coverage.
Both SDKs are thin, open-source (MIT) wrappers around the REST API: they send your key, build the query strings, turn error responses into typed exceptions and read the credit headers for you. Every method maps to one endpoint and costs what that endpoint costs, so the pricing is the same as calling the API directly. The source lives on GitHub at fetchtranscript/python-sdk and fetchtranscript/js-sdk.
Installation
The Python package needs Python 3.9 or newer and has a single dependency, httpx; it ships type hints (py.typed). The TypeScript package needs Node.js 18 or newer (it uses the built-in fetch), has no runtime dependencies and ships both ES module and CommonJS builds with type definitions. Install the latest version from PyPI or npm:
Python
pip install fetchtranscriptTypeScript
npm install fetchtranscriptQuick Start
from fetchtranscript import FetchTranscriptClient
client = FetchTranscriptClient(api_key="yt_your_api_key")
# Get transcript (JSON: timed segments)
transcript = client.transcripts.get("dQw4w9WgXcQ")
for segment in transcript["segments"]:
print(segment["start"], segment["text"])
# Get as plain text
text = client.transcripts.get_text("dQw4w9WgXcQ")
# Get as SRT subtitles
srt = client.transcripts.get_srt("dQw4w9WgXcQ")
# List available languages
languages = client.transcripts.list_languages("dQw4w9WgXcQ")
for lang in languages["languages"]:
print(f"{lang['language']} ({lang['language_code']})")Videos & Channels
# Video metadata
metadata = client.videos.get_metadata("dQw4w9WgXcQ")
print(f"{metadata['title']} - {metadata['view_count']:,} views")
# Chapters & comments
chapters = client.videos.get_chapters("dQw4w9WgXcQ")
comments = client.videos.get_comments("dQw4w9WgXcQ", limit=50)
# Channel info & videos
channel = client.channels.get_info("@mkbhd")
videos = client.channels.get_videos("@mkbhd", limit=20)
all_videos = client.channels.get_all_videos("@mkbhd")
# Search
results = client.search.videos("python tutorial", limit=10)Pagination, Comments and Search
- -Channel videos.
get_videos/getVideosreturns one page:limitfrom 1 to 100 (default 30), anoffsetto skip, andhas_morein the response. Shorts are left out unless you passinclude_shorts/includeShorts. Each page costs 1 credit. - -Every video of a channel.
get_all_videos/getAllVideoswalks the pages for you, 100 videos per request, untilhas_moreis false or it reachesmax_videos/maxVideos(default 500). Fetching 500 videos therefore costs 5 credits. - -Comments.
get_comments/getCommentstakeslimit(1-500, default 100) andsort:"top"(default) or"new"for newest first. It costs 1 credit per 100 comments returned, rounded up; videos with comments turned off raise an error and cost nothing. - -Search.
search.videosreturns up to 50 results (default 10). The Python SDK also hasfind_videos_with_transcripts, which runs the search and then lists the transcript languages of every result: that is one call for the search plus one per video, each billed.
# Newest 200 comments (2 credits)
comments = client.videos.get_comments("dQw4w9WgXcQ", limit=200, sort="new")
# Up to 1,000 videos of a channel, Shorts included (1 credit per 100)
videos = client.channels.get_all_videos("@mkbhd", include_shorts=True, max_videos=1000)
# Manual paging
page = client.channels.get_videos("@mkbhd", limit=100, offset=100)
print(page["has_more"])Async Support (Python)
The Python package has two clients with the same methods: FetchTranscriptClient (synchronous) and AsyncFetchTranscriptClient, where every method is awaitable. Use the async one in FastAPI, aiohttp or any asyncio code, and to fetch many videos concurrently with asyncio.gather (the API allows 500 requests per minute). Both work as context managers, which close the underlying HTTP connection pool; otherwise call close() (or await client.close()) when you are done. The TypeScript client is promise-based and needs no closing.
import asyncio
from fetchtranscript import AsyncFetchTranscriptClient
async def main():
async with AsyncFetchTranscriptClient(api_key="yt_your_api_key") as client:
transcript = await client.transcripts.get("dQw4w9WgXcQ")
print(transcript["text"])
asyncio.run(main())Error Handling
Any non-2xx response raises an exception. All of them extend FetchTranscriptError, which carries the API's message and the HTTP status (status_code in Python, statusCode in TypeScript). The subclass tells you what went wrong:
| Exception | Raised for |
|---|---|
| VideoNotFoundError | 404: video_not_found, transcripts_disabled, no_transcript_found, comments_disabled |
| ChannelNotFoundError | 404: channel_not_found (Python; the TypeScript SDK currently raises VideoNotFoundError for every 404) |
| InvalidVideoIdError | 400: invalid_video_id, invalid_channel_id |
| AuthenticationError | 401: missing_api_key, invalid_api_key |
| InsufficientCreditsError | 402: insufficient_credits |
| ServiceUnavailableError | 503: service_unavailable (temporary, retry with backoff) |
| FetchTranscriptError | Base class; raised as is for any other status, such as 429 |
A 429 (more than 500 requests per minute, or a key retrying with no credits) raises the base FetchTranscriptError with status 429: wait before retrying, as the API's Retry-After header says. Not-found and invalid-ID errors will not succeed on retry, and failed calls cost no credits. See the error reference for every code.
from fetchtranscript import (
FetchTranscriptClient,
VideoNotFoundError,
InsufficientCreditsError,
AuthenticationError,
)
client = FetchTranscriptClient(api_key="yt_your_api_key")
try:
transcript = client.transcripts.get("invalid_id")
except VideoNotFoundError as e:
print(f"Video not found: {e.message}")
except InsufficientCreditsError:
print("Not enough credits")
except AuthenticationError:
print("Invalid API key")Response Metadata
After any API call, check remaining credits and processing time via client properties. They are read from the last response's X-Credits-Remaining and X-Processing-Time headers, and are empty until the first call.
client.transcripts.get("dQw4w9WgXcQ")
print(client.credits_remaining)
print(client.processing_time_ms)Configuration
| Option | Default | Description |
|---|---|---|
api_key / apiKey | required | Your API key (starts with yt_), sent as the X-API-Key header |
base_url / baseUrl | https://api.fetchtranscript.com | API base URL, without /v1 |
timeout | 30 s (Python) / 30000 ms (TypeScript) | Request timeout: seconds in Python, milliseconds in TypeScript |
The SDKs do not read environment variables on their own, so keep the key out of your source code and pass it in yourself, for example from an environment variable:
import os
from fetchtranscript import FetchTranscriptClient
client = FetchTranscriptClient(
api_key=os.environ["FETCHTRANSCRIPT_API_KEY"],
timeout=60.0,
)