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 fetchtranscript

TypeScript

npm install fetchtranscript

Quick 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 / getVideos returns one page: limit from 1 to 100 (default 30), an offset to skip, and has_more in the response. Shorts are left out unless you pass include_shorts / includeShorts. Each page costs 1 credit.
  • -Every video of a channel. get_all_videos / getAllVideos walks the pages for you, 100 videos per request, until has_more is false or it reaches max_videos / maxVideos (default 500). Fetching 500 videos therefore costs 5 credits.
  • -Comments. get_comments / getComments takes limit (1-500, default 100) and sort: "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.videos returns up to 50 results (default 10). The Python SDK also has find_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:

ExceptionRaised for
VideoNotFoundError404: video_not_found, transcripts_disabled, no_transcript_found, comments_disabled
ChannelNotFoundError404: channel_not_found (Python; the TypeScript SDK currently raises VideoNotFoundError for every 404)
InvalidVideoIdError400: invalid_video_id, invalid_channel_id
AuthenticationError401: missing_api_key, invalid_api_key
InsufficientCreditsError402: insufficient_credits
ServiceUnavailableError503: service_unavailable (temporary, retry with backoff)
FetchTranscriptErrorBase 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

OptionDefaultDescription
api_key / apiKeyrequiredYour API key (starts with yt_), sent as the X-API-Key header
base_url / baseUrlhttps://api.fetchtranscript.comAPI base URL, without /v1
timeout30 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,
)

Resources