API Reference
Complete reference for all available API endpoints.
https://api.fetchtranscript.com/v1
Bearer Token or X-API-Key Header
Response Headers
All successful responses include these custom headers:
| Header | Description |
|---|---|
| X-Processing-Time | Request processing time in milliseconds |
| X-Credits-Remaining | Number of credits remaining after this request |
Common Error Codes
All authenticated endpoints may return these error codes:
| Status | Error Code | Description |
|---|---|---|
| 401 | missing_api_key | No API key provided in request |
| 401 | invalid_api_key | API key is invalid or inactive |
| 402 | insufficient_credits | Account has no credits remaining |
| 429 | rate_limit_exceeded | Too many requests, please slow down |
See the Error Handling page for complete error documentation.
Transcripts
/v1/transcripts/{video_id}Get the transcript for a YouTube video.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| video_id | string | YouTube video ID (11 characters) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| lang | string | video default | Language code (e.g., "en", "es", "fr"). Without it, the video's default transcript language is returned. |
| format | string | json | Response 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.
{
"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..."
}
}{
"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..."
}
}/v1/transcripts/{video_id}/languagesList available transcript languages for a video.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| video_id | string | YouTube video ID (11 characters) |
Response
{
"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
/v1/videos/{video_id}Get video metadata including title, views, likes, duration, and more.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| video_id | string | YouTube video ID (11 characters) |
Response
{
"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"]
}/v1/videos/{video_id}/chaptersGet video chapters/timestamps if available.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| video_id | string | YouTube video ID (11 characters) |
Response
{
"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
}/v1/videos/{video_id}/commentsGet 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
| Parameter | Type | Description |
|---|---|---|
| video_id | string | YouTube video ID (11 characters) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 100 | Max comments to fetch (1-500) |
| sort | string | top | top (YouTube's top comments) or new (newest first) |
Response
{
"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-Usedheader says what the call cost. If your balance pays for fewer comments thanlimit, you get as many as it pays for andhas_moreis true. total_countis the video's comment count as YouTube shows it (replies included, rounded for large numbers).has_moreis true when the page came back full and the video has more comments.published_atis an ISO-8601 UTC estimate: YouTube only shows relative times such as "3 days ago".- Videos with comments turned off answer 404
comments_disabledand cost nothing.
Channels
/v1/channels/{channel_id}Get channel metadata including name, description, subscriber count, and more.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| channel_id | string | Channel ID (@handle or UCxxxxxx format) |
Response
{
"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.
/v1/channels/{channel_id}/videosList videos from a YouTube channel with pagination.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| channel_id | string | Channel ID (@handle or UCxxxxxx format) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 30 | Videos per page (1-100) |
| offset | integer | 0 | Number of videos to skip |
| include_shorts | boolean | false | Include YouTube Shorts |
Response
{
"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_countis null (YouTube does not show how many long-form videos a channel has) andhas_moremeans the page came back full: the page after the last full one can be empty. - With
include_shorts=truethe whole channel is listed, videos and Shorts sorted by view count, andtotal_countis their number. It is slower on large channels. descriptionis null: YouTube's channel lists do not carry it. UseGET /v1/videos/{video_id}for the full description.
Search
/v1/searchSearch YouTube videos by query.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| q | string | required | Search query (1-500 characters) |
| limit | integer | 10 | Max results (1-50) |
Response
{
"query": "rick astley",
"results": [
{
"video_id": "dQw4w9WgXcQ",
"title": "Rick Astley - Never Gonna Give You Up",
"description": "The official video...",
"channel_name": "Rick Astley",
"channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
"duration": 212,
"view_count": 1400000000,
"thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
"upload_date": null
}
],
"total_results": 10
}Results are videos only (channels and playlists in YouTube's results are left out). upload_date is null in search results: use GET /v1/videos/{video_id} for the date.