API Reference

Complete reference for all available API endpoints.

Base URL

https://api.fetchtranscript.com/v1

Authentication

Bearer Token or X-API-Key Header

Response Headers

All successful responses include these custom headers:

HeaderDescription
X-Processing-TimeRequest processing time in milliseconds
X-Credits-RemainingNumber of credits remaining after this request

Common Error Codes

All authenticated endpoints may return these error codes:

StatusError CodeDescription
401missing_api_keyNo API key provided in request
401invalid_api_keyAPI key is invalid or inactive
402insufficient_creditsAccount has no credits remaining
429rate_limit_exceededToo many requests, please slow down

See the Error Handling page for complete error documentation.

Transcripts

GET/v1/transcripts/{video_id}

Get the transcript for a YouTube video.

Path Parameters

ParameterTypeDescription
video_idstringYouTube video ID (11 characters)

Query Parameters

ParameterTypeDefaultDescription
langstringvideo defaultLanguage code (e.g., "en", "es", "fr"). Without it, the video's default transcript language is returned.
formatstringjsonResponse format: json, text, or srt

Response

For format=json, segments are returned. For format=text or format=srt, the full text is returned instead of segments.

JSON (format=json)
{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "segments": [
    {
      "text": "We're no strangers to love",
      "start": 0.0,
      "duration": 2.5
    }
  ],
  "is_generated": false,
  "provider": "youtube_transcript_api",
  "metadata": {
    "title": "Rick Astley - Never Gonna Give You Up",
    "author": "Rick Astley",
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "length_seconds": 212,
    "view_count": 1400000000,
    "short_description": "The official video for..."
  }
}
JSON (format=text)
{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "text": "We're no strangers to love...",
  "is_generated": false,
  "provider": "youtube_transcript_api",
  "metadata": {
    "title": "Rick Astley - Never Gonna Give You Up",
    "author": "Rick Astley",
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "length_seconds": 212,
    "view_count": 1400000000,
    "short_description": "The official video for..."
  }
}
GET/v1/transcripts/{video_id}/languages

List available transcript languages for a video.

Path Parameters

ParameterTypeDescription
video_idstringYouTube video ID (11 characters)

Response

JSON
{
  "video_id": "dQw4w9WgXcQ",
  "languages": [
    {
      "language_code": "en",
      "language": "English",
      "is_generated": false,
      "is_translatable": true
    },
    {
      "language_code": "es",
      "language": "Spanish",
      "is_generated": true,
      "is_translatable": true
    }
  ]
}

Videos

GET/v1/videos/{video_id}

Get video metadata including title, views, likes, duration, and more.

Path Parameters

ParameterTypeDescription
video_idstringYouTube video ID (11 characters)

Response

JSON
{
  "video_id": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up",
  "description": "The official video for...",
  "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "channel_name": "Rick Astley",
  "duration": 212,
  "view_count": 1400000000,
  "like_count": 15000000,
  "comment_count": 2500000,
  "upload_date": "20091025",
  "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "tags": ["rick astley", "never gonna give you up"],
  "categories": ["Music"]
}
GET/v1/videos/{video_id}/chapters

Get video chapters/timestamps if available.

Path Parameters

ParameterTypeDescription
video_idstringYouTube video ID (11 characters)

Response

JSON
{
  "video_id": "dQw4w9WgXcQ",
  "chapters": [
    {
      "title": "Intro",
      "start_time": 0.0,
      "end_time": 30.0
    },
    {
      "title": "Verse 1",
      "start_time": 30.0,
      "end_time": 60.0
    }
  ],
  "has_chapters": true
}
GET/v1/videos/{video_id}/comments

Get the top-level comments of a video (replies are not included; each comment carries its reply_count). Costs 1 credit per 100 comments returned, rounded up (minimum 1).

Path Parameters

ParameterTypeDescription
video_idstringYouTube video ID (11 characters)

Query Parameters

ParameterTypeDefaultDescription
limitinteger100Max comments to fetch (1-500)
sortstringtoptop (YouTube's top comments) or new (newest first)

Response

JSON
{
  "video_id": "dQw4w9WgXcQ",
  "comments": [
    {
      "comment_id": "abc123",
      "text": "Great video!",
      "author": "John Doe",
      "author_id": "UCxxxxxx",
      "like_count": 100,
      "reply_count": 5,
      "published_at": "2023-01-01T00:00:00Z",
      "is_pinned": false
    }
  ],
  "total_count": 2500000,
  "has_more": true
}
  • Pricing: 1 credit per 100 comments returned, rounded up (minimum 1): up to 100 comments cost 1 credit, 101-200 cost 2, 500 cost 5. The X-Credits-Used header says what the call cost. If your balance pays for fewer comments than limit, you get as many as it pays for and has_more is true.
  • total_count is the video's comment count as YouTube shows it (replies included, rounded for large numbers). has_more is true when the page came back full and the video has more comments.
  • published_at is an ISO-8601 UTC estimate: YouTube only shows relative times such as "3 days ago".
  • Videos with comments turned off answer 404 comments_disabled and cost nothing.

Channels

GET/v1/channels/{channel_id}

Get channel metadata including name, description, subscriber count, and more.

Path Parameters

ParameterTypeDescription
channel_idstringChannel ID (@handle or UCxxxxxx format)

Response

JSON
{
  "channel_id": "UCBcRF18a7Qf58cCRy5xuWwQ",
  "name": "MKBHD",
  "description": "Quality Tech Videos...",
  "subscriber_count": 18000000,
  "video_count": 1500,
  "thumbnail_url": "https://yt3.googleusercontent.com/...",
  "channel_url": "https://www.youtube.com/channel/UCBcRF18a7Qf58cCRy5xuWwQ"
}

video_count is the number of videos the channel page shows (all public uploads, Shorts included; rounded by YouTube above 1,000, e.g. 6.1K = 6100). subscriber_count and video_count are null when the channel hides them.

GET/v1/channels/{channel_id}/videos

List videos from a YouTube channel with pagination.

Path Parameters

ParameterTypeDescription
channel_idstringChannel ID (@handle or UCxxxxxx format)

Query Parameters

ParameterTypeDefaultDescription
limitinteger30Videos per page (1-100)
offsetinteger0Number of videos to skip
include_shortsbooleanfalseInclude YouTube Shorts

Response

JSON
{
  "channel_id": "UCBcRF18a7Qf58cCRy5xuWwQ",
  "videos": [
    {
      "video_id": "dQw4w9WgXcQ",
      "title": "Sample Video Title",
      "description": "Video description...",
      "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "duration": 212,
      "view_count": 1000000
    }
  ],
  "total_count": 1500,
  "offset": 0,
  "limit": 30,
  "has_more": true
}
  • Without Shorts (default) videos come newest first, total_count is null (YouTube does not show how many long-form videos a channel has) and has_more means the page came back full: the page after the last full one can be empty.
  • With include_shorts=true the whole channel is listed, videos and Shorts sorted by view count, and total_count is their number. It is slower on large channels.
  • description is null: YouTube's channel lists do not carry it. Use GET /v1/videos/{video_id} for the full description.