YouTube Transcript API Reference

The YouTube Transcript API provides a simple and reliable way to extract transcripts from YouTube videos programmatically. This complete reference covers authentication, request parameters, response formats, and practical examples.

Want to test the API interactively? Try our Swagger UI where you can make live requests right in your browser.

Base URL

All API requests are made to:

https://transcriptapi.com/api/v2

Endpoints

The API provides the following endpoints:

Endpoint	Description	Credits
`GET /youtube/transcript`	Extract video transcript	1
`GET /youtube/search`	Search YouTube videos or channels	1
`GET /youtube/channel/resolve`	Resolve @handle/URL to channel ID	Free
`GET /youtube/channel/search`	Search within a channel	1
`GET /youtube/channel/videos`	Paginated channel uploads	1/page
`GET /youtube/channel/latest`	Latest 15 videos via RSS	Free
`GET /youtube/playlist/videos`	Paginated playlist videos	1/page

Quick Start

Here’s how to make your first API request:

curl -X GET "https://transcriptapi.com/api/v2/youtube/transcript?video_url=dQw4w9WgXcQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

Don’t have an API key yet? Get one from your dashboard.

Expected Response:

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    {
      "text": "Never gonna give you up",
      "start": 0.0,
      "duration": 4.12
    },
    {
      "text": "Never gonna let you down",
      "start": 4.12,
      "duration": 3.85
    }
  ]
}

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Example:

curl -X GET "https://transcriptapi.com/api/v2/youtube/transcript?video_url=..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Get your API key from your API Keys dashboard.

Request Parameters

video_url (required)

The YouTube video URL or video ID to fetch transcripts for.

Property	Value
Type	`string`
Pattern	`^([a-zA-Z0-9_-]{11}\|https?://.\*)$`
Required	Yes

Accepted Formats:

Full YouTube URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ
Short YouTube URL: https://youtu.be/dQw4w9WgXcQ
Video ID only: dQw4w9WgXcQ

Examples:

# Full URL
?video_url=https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Short URL
?video_url=https://youtu.be/dQw4w9WgXcQ

# Video ID only
?video_url=dQw4w9WgXcQ

format (optional)

The output format for the transcript response.

Property	Value
Type	`string`
Values	`json`, `text`
Default	`json`

json: Returns structured data with transcript segments
text: Returns plain text transcript

include_timestamp (optional)

Whether to include timestamps in the transcript output.

Property	Value
Type	`boolean`
Default	`true`

Behavior Matrix:

Format	include_timestamp	Output
`json`	`true`	Segments with `text`, `start`, `duration`
`json`	`false`	Segments with only `text`
`text`	`true`	Lines formatted as `[123.45s] text`
`text`	`false`	Plain concatenated text

send_metadata (optional)

Whether to include video metadata in the response.

Property	Value
Type	`boolean`
Default	`false`

When enabled, includes:

title: Video title
author_name: Channel name
author_url: Channel URL
thumbnail_url: Video thumbnail

Response Formats

The API supports multiple response formats based on your parameters:

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    {
      "text": "Never gonna give you up",
      "start": 0.0,
      "duration": 4.12
    },
    {
      "text": "Never gonna let you down",
      "start": 4.12,
      "duration": 3.85
    }
  ],
  "metadata": {
    "title": "Rick Astley - Never Gonna Give You Up",
    "author_name": "RickAstleyVEVO",
    "author_url": "https://www.youtube.com/@RickAstley",
    "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"
  }
}

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    {
      "text": "Never gonna give you up"
    },
    {
      "text": "Never gonna let you down"
    }
  ]
}

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": "[0.0s] Never gonna give you up\n[4.12s] Never gonna let you down\n[7.97s] Never gonna run around and desert you"
}

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": "Never gonna give you up Never gonna let you down Never gonna run around and desert you"
}

Response Headers

Header	Description
`X-Cache-Status`	Cache status: `HIT`, `PARTIAL-HIT`, or `MISS`

Search Endpoint

GET /youtube/search

Search YouTube for videos or channels.

Parameters

Parameter	Type	Required	Default	Description
`q`	string	Yes	—	Search query (1–200 characters)
`type`	string	No	`video`	Result type: `video` or `channel`
`limit`	integer	No	`20`	Max results to return (1–50)

{
  "results": [
    {
      "type": "video",
      "videoId": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
      "channelTitle": "Rick Astley",
      "channelHandle": "@RickAstley",
      "channelVerified": true,
      "lengthText": "3:33",
      "viewCountText": "1.5B views",
      "publishedTimeText": "14 years ago",
      "hasCaptions": true,
      "thumbnails": [
        {"url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg", "width": 120, "height": 90}
      ]
    }
  ],
  "result_count": 20
}

{
  "results": [
    {
      "type": "channel",
      "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
      "title": "Rick Astley",
      "handle": "@RickAstley",
      "url": "https://www.youtube.com/@RickAstley",
      "description": "Official channel...",
      "subscriberCount": "4.2M subscribers",
      "verified": true,
      "rssUrl": "https://www.youtube.com/feeds/videos.xml?channel_id=UCuAXFkgsw1L7xaCfnd5JJOw",
      "thumbnails": [...]
    }
  ],
  "result_count": 5
}

Example:

curl -X GET "https://transcriptapi.com/api/v2/youtube/search?q=python+tutorial&type=video&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Channel Endpoints

Resolve Channel

GET /youtube/channel/resolve

Resolve any channel reference (@handle, URL, or UC… ID) to a canonical UC… channel ID. Free — no credits charged.

Parameter	Type	Required	Description
`input`	string	Yes	@handle, channel URL, or UC… ID (1–200 characters)

Response:

{
  "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "resolved_from": "@mkbhd"
}

Example:

curl -X GET "https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@mkbhd" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search Within Channel

GET /youtube/channel/search

Search for videos within a specific channel.

Parameter	Type	Required	Default	Description
`channel_id`	string	Yes	—	Channel ID (must start with `UC`, 24 characters)
`q`	string	Yes	—	Search query (1–200 characters)
`limit`	integer	No	`30`	Max results (1–50)

Response:

{
  "results": [
    {
      "type": "video",
      "videoId": "abc123xyz00",
      "title": "Video Title",
      "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
      "channelTitle": "MKBHD",
      "channelHandle": "@mkbhd",
      "channelVerified": true,
      "lengthText": "12:34",
      "viewCountText": "2.1M views",
      "publishedTimeText": "3 months ago",
      "hasCaptions": true,
      "thumbnails": [...]
    }
  ],
  "result_count": 12
}

Example:

curl -X GET "https://transcriptapi.com/api/v2/youtube/channel/search?channel_id=UCBcRF18a7Qf58cCRy5xuWwQ&q=review&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Channel Videos (Paginated)

GET /youtube/channel/videos

List all videos uploaded to a channel, paginated at ~100 per page.

Parameter	Type	Required	Description
`channel_id`	string	Conditional	Channel ID (first page). Must start with `UC`.
`continuation`	string	Conditional	Continuation token from previous response (next pages).

Provide exactly one of channel_id or continuation.

Response:

{
  "results": [
    {
      "videoId": "abc123xyz00",
      "title": "Latest Video",
      "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
      "channelTitle": "MKBHD",
      "channelHandle": "@mkbhd",
      "lengthText": "15:22",
      "viewCountText": "3.2M views 2 weeks ago",
      "thumbnails": [...],
      "index": "0"
    }
  ],
  "playlist_info": {
    "title": "Uploads from MKBHD",
    "numVideos": "1893",
    "description": "",
    "ownerName": "MKBHD",
    "viewCount": null
  },
  "continuation_token": "4qmFsgKlARIYVVV1QVhGa2dz...",
  "has_more": true
}

Pagination flow:

First request: ?channel_id=UCuAXFkgsw1L7xaCfnd5JJOw — returns first ~100 videos + continuation_token
Next request: ?continuation=4qmFsgKlARIYVVV1QVhGa2dz... — returns next ~100 + new token
Repeat until has_more is false or continuation_token is null

Example:

# First page
curl -X GET "https://transcriptapi.com/api/v2/youtube/channel/videos?channel_id=UCBcRF18a7Qf58cCRy5xuWwQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page
curl -X GET "https://transcriptapi.com/api/v2/youtube/channel/videos?continuation=4qmFsgKlARIYVVV1QVhGa2dz..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Channel Latest (RSS)

GET /youtube/channel/latest

Get the latest 15 videos from a channel via YouTube RSS feed. Returns exact publish timestamps and view counts. Free — no credits charged.

Parameter	Type	Required	Description
`channel_id`	string	Yes	Channel ID (must start with `UC`, 24 characters)

Response:

{
  "channel": {
    "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
    "title": "MKBHD",
    "author": "MKBHD",
    "url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
    "published": "2008-03-21T00:00:00Z"
  },
  "results": [
    {
      "videoId": "abc123xyz00",
      "title": "Latest Video Title",
      "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
      "author": "MKBHD",
      "published": "2026-01-30T16:00:00Z",
      "updated": "2026-01-31T02:00:00Z",
      "link": "https://www.youtube.com/watch?v=abc123xyz00",
      "description": "Full video description...",
      "thumbnail": {"url": "https://i1.ytimg.com/vi/abc123xyz00/hqdefault.jpg", "width": "480", "height": "360"},
      "viewCount": "2287630",
      "starRating": {"average": "4.92", "count": "45000", "min": "1", "max": "5"}
    }
  ],
  "result_count": 15
}

Example:

curl -X GET "https://transcriptapi.com/api/v2/youtube/channel/latest?channel_id=UCBcRF18a7Qf58cCRy5xuWwQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

Playlist Endpoint

GET /youtube/playlist/videos

List videos in a playlist, paginated at ~100 per page.

Parameter	Type	Required	Description
`playlist_id`	string	Conditional	Playlist ID (first page). Must start with `PL`, `UU`, `LL`, `FL`, or `OL`.
`continuation`	string	Conditional	Continuation token from previous response (next pages).

Provide exactly one of playlist_id or continuation.

Response:

{
  "results": [
    {
      "videoId": "abc123xyz00",
      "title": "Playlist Video",
      "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
      "channelTitle": "MKBHD",
      "channelHandle": "@mkbhd",
      "lengthText": "10:05",
      "viewCountText": "1.5M views 6 months ago",
      "thumbnails": [...],
      "index": "0"
    }
  ],
  "playlist_info": {
    "title": "Best Tech of 2025",
    "numVideos": "47",
    "description": "My picks for the best tech this year",
    "ownerName": "MKBHD",
    "viewCount": "5000000"
  },
  "continuation_token": "4qmFsgKlARIYVVV1QVhGa2dz...",
  "has_more": true
}

Pagination: Same flow as channel/videos — use continuation_token from each response to fetch the next page.

Example:

# First page
curl -X GET "https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist_id=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page
curl -X GET "https://transcriptapi.com/api/v2/youtube/playlist/videos?continuation=4qmFsgKlARIYVVV1QVhGa2dz..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Credit Usage & Billing

Credit Cost

Endpoint	Credits per Request	Notes
`GET /youtube/transcript`	1 credit	Only charged on successful response (200)
`GET /youtube/search`	1 credit	Search videos or channels
`GET /youtube/channel/resolve`	Free	Requires auth + at least 1 active credit
`GET /youtube/channel/search`	1 credit	Search within a channel
`GET /youtube/channel/videos`	1 credit/page	Paginated — each page costs 1 credit
`GET /youtube/channel/latest`	Free	Requires auth + at least 1 active credit
`GET /youtube/playlist/videos`	1 credit/page	Paginated — each page costs 1 credit

When Credits Are Charged

✅ Successful requests (HTTP 200) - 1 credit (paid endpoints only)
✅ Cached responses (HTTP 200) - 1 credit (paid endpoints only)
✅ Free endpoints (HTTP 200) - 0 credits (requires at least 1 active credit)
❌ Failed requests (4xx, 5xx errors) - 0 credits
❌ Rate limited requests (HTTP 429) - 0 credits

Credits are deducted in real-time only when a request is successfully returned.

When credits are exhausted, the API returns HTTP 402 Payment Required.

Rate Limits

All API keys are subject to the following rate limits:

300 requests per minute per API key

Rate Limit Headers

Each response includes rate limit information in the headers:

Header	Description
`X-RateLimit-Limit`	Total allowed requests in the window
`X-RateLimit-Remaining`	Remaining requests in the window
`X-RateLimit-Reset`	UTC epoch seconds when the window resets
`Retry-After`	Seconds until you can retry (only on 429)

Example Headers:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1678901234

Best Practices

Implement exponential backoff on 429 errors
Respect the Retry-After header value
Cache responses when appropriate to reduce API calls
Don’t retry failed requests more than 2 times within 3 seconds
Monitor rate limit headers to avoid hitting limits

Error Handling

The API uses standard HTTP status codes:

Status Code	Meaning	Retry?	Action
`200`	Success	—	Transcript returned, 1 credit charged
`400`	Bad Request	❌ No	Check your request parameters
`401`	Unauthorized	❌ No	Invalid or missing API key
`402`	Payment Required	❌ No	No credits remaining - visit billing
`404`	Not Found	❌ No	Video not found or transcript unavailable
`408`	Timeout / Retry	✅ Yes	Temporary failure (bot detection, network) - retry in 1-5s
`422`	Validation Error	❌ No	Invalid YouTube URL or ID
`429`	Too Many Requests	✅ Yes	Rate limit exceeded - retry after `Retry-After` header
`500`	Server Error	⚠️ Maybe	Contact support if persistent
`503`	Service Unavailable	✅ Yes	Service temporarily down - retry in 1-5s

Retry Strategy

For retryable errors (408, 429, 503):

Wait the recommended delay (1-5 seconds, or check Retry-After header for 429)
Retry up to 2-3 times with exponential backoff
Give up after max retries and log the failure

For non-retryable errors (400, 401, 402, 404, 422): Do not retry - fix the request parameters or check your account status.

Error Response Format

All error responses follow this format:

{
  "detail": "Human-readable error message",
  "code": "ERROR_CODE"
}

401 Unauthorized

Includes a WWW-Authenticate header:

WWW-Authenticate: Bearer

402 Payment Required

Special format with action details:

Insufficient Credits:

{
  "detail": {
    "message": "You have an active plan, but you've run out of credits.",
    "reason": "insufficient_credits",
    "action_label": "Top up credits",
    "action_url": "https://transcriptapi.com/top-up"
  }
}

No Active Plan:

{
  "detail": {
    "message": "You don't have an active paid plan yet.",
    "reason": "no_active_paid_plan",
    "action_label": "Go to billing to choose a plan",
    "action_url": "https://transcriptapi.com/billing"
  }
}

Code Examples

Here are complete examples in multiple languages:

# Basic request
curl -X GET "https://transcriptapi.com/api/v2/youtube/transcript?video_url=dQw4w9WgXcQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

# With all parameters
curl -X GET "https://transcriptapi.com/api/v2/youtube/transcript?video_url=dQw4w9WgXcQ&format=json&include_timestamp=true&send_metadata=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Text format without timestamps
curl -X GET "https://transcriptapi.com/api/v2/youtube/transcript?video_url=dQw4w9WgXcQ&format=text&include_timestamp=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests
import json

# Configuration
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://transcriptapi.com/api/v2"

def get_transcript(video_url, format="json", include_timestamp=True, send_metadata=False):
    """Fetch YouTube video transcript"""

    headers = {
        "Authorization": f"Bearer {API_KEY}"
    }

    params = {
        "video_url": video_url,
        "format": format,
        "include_timestamp": include_timestamp,
        "send_metadata": send_metadata
    }

    try:
        response = requests.get(
            f"{BASE_URL}/youtube/transcript",
            headers=headers,
            params=params
        )

        # Check for errors
        response.raise_for_status()

        # Parse JSON response
        data = response.json()

        # Handle different formats
        if format == "json":
            transcript = data["transcript"]
            if include_timestamp:
                for segment in transcript:
                    print(f"[{segment['start']}s] {segment['text']}")
            else:
                for segment in transcript:
                    print(segment['text'])
        else:
            # Text format
            print(data["transcript"])

        return data

    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 402:
            error_data = e.response.json()
            print(f"Payment required: {error_data['detail']['message']}")
            print(f"Action: {error_data['detail']['action_url']}")
        elif e.response.status_code in (408, 429, 503):
            # Retryable errors - implement backoff
            retry_after = e.response.headers.get('Retry-After', '5')
            print(f"Retryable error ({e.response.status_code}). Retry after {retry_after} seconds")
        elif e.response.status_code == 404:
            print("Video not found or has no transcript available")
        else:
            print(f"HTTP error: {e}")
    except Exception as e:
        print(f"Error: {e}")

# Example usage
if __name__ == "__main__":
    # Basic usage
    get_transcript("dQw4w9WgXcQ")

    # With metadata
    data = get_transcript(
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        send_metadata=True
    )

    if data and "metadata" in data:
        print(f"Title: {data['metadata']['title']}")
        print(f"Author: {data['metadata']['author_name']}")

// Using native fetch (Node.js 18+) or install node-fetch for older versions
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://transcriptapi.com/api/v2';

async function getTranscript(videoUrl, options = {}) {
  const {
    format = 'json',
    includeTimestamp = true,
    sendMetadata = false
  } = options;

  const params = new URLSearchParams({
    video_url: videoUrl,
    format: format,
    include_timestamp: includeTimestamp,
    send_metadata: sendMetadata
  });

  try {
    const response = await fetch(
      `${BASE_URL}/youtube/transcript?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    );

    if (!response.ok) {
      const error = await response.json();

      if (response.status === 402) {
        console.error('Payment required:', error.detail.message);
        console.error('Action:', error.detail.action_url);
      } else if ([408, 429, 503].includes(response.status)) {
        // Retryable errors - implement backoff
        const retryAfter = response.headers.get('Retry-After') || '5';
        console.error(`Retryable error (${response.status}). Retry after ${retryAfter} seconds`);
      } else if (response.status === 404) {
        console.error('Video not found or has no transcript available');
      } else {
        console.error('API Error:', error.detail);
      }

      throw new Error(error.detail);
    }

    const data = await response.json();

    // Process transcript based on format
    if (format === 'json' && includeTimestamp) {
      data.transcript.forEach(segment => {
        console.log(`[${segment.start}s] ${segment.text}`);
      });
    }

    return data;

  } catch (error) {
    console.error('Error fetching transcript:', error);
    throw error;
  }
}

// Example usage with async/await
(async () => {
  try {
    // Basic usage
    const transcript = await getTranscript('dQw4w9WgXcQ');
    console.log('Video ID:', transcript.video_id);

    // With metadata
    const withMetadata = await getTranscript(
      'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
      { sendMetadata: true }
    );

    if (withMetadata.metadata) {
      console.log('Title:', withMetadata.metadata.title);
      console.log('Author:', withMetadata.metadata.author_name);
    }

    // Text format without timestamps
    const plainText = await getTranscript('dQw4w9WgXcQ', {
      format: 'text',
      includeTimestamp: false
    });
    console.log('Plain text:', plainText.transcript);

  } catch (error) {
    // Error already logged
  }
})();

// Browser JavaScript with Fetch API
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://transcriptapi.com/api/v2';

async function getYouTubeTranscript(videoUrl, options = {}) {
  const {
    format = 'json',
    includeTimestamp = true,
    sendMetadata = false
  } = options;

  const params = new URLSearchParams({
    video_url: videoUrl,
    format: format,
    include_timestamp: includeTimestamp,
    send_metadata: sendMetadata
  });

  try {
    const response = await fetch(
      `${BASE_URL}/youtube/transcript?${params}`,
      {
        method: 'GET',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    if (!response.ok) {
      const error = await response.json();

      // Handle specific error cases
      switch (response.status) {
        case 401:
          throw new Error('Invalid API key');
        case 402:
          // Show payment required UI
          window.location.href = error.detail.action_url;
          break;
        case 404:
          throw new Error('Video not found or has no transcript');
        case 408:
        case 503:
          // Retryable - temporary failure
          throw new Error('Temporary failure. Please retry in a few seconds.');
        case 429:
          const retryAfter = response.headers.get('Retry-After');
          throw new Error(`Rate limited. Retry after ${retryAfter}s`);
        default:
          throw new Error(error.detail || 'API request failed');
      }
    }

    return await response.json();

  } catch (error) {
    console.error('Transcript fetch error:', error);

    // Display user-friendly error
    if (error.message.includes('Failed to fetch')) {
      throw new Error('Network error. Please check your connection.');
    }

    throw error;
  }
}

// Example: Display transcript in DOM
async function displayTranscript(videoUrl) {
  const container = document.getElementById('transcript-container');
  container.innerHTML = 'Loading transcript...';

  try {
    const data = await getYouTubeTranscript(videoUrl, {
      sendMetadata: true
    });

    // Display metadata if available
    if (data.metadata) {
      container.innerHTML = `
        <h3>${data.metadata.title}</h3>
        <p>By: ${data.metadata.author_name}</p>
      `;
    }

    // Display transcript
    const transcriptHtml = data.transcript
      .map(segment => `
        <div class="transcript-segment">
          <span class="timestamp">[${segment.start}s]</span>
          <span class="text">${segment.text}</span>
        </div>
      `)
      .join('');

    container.innerHTML += `<div class="transcript">${transcriptHtml}</div>`;

  } catch (error) {
    container.innerHTML = `
      <div class="error">
        Error: ${error.message}
      </div>
    `;
  }
}

// Usage
displayTranscript('dQw4w9WgXcQ');

Best Practices

Error Handling Strategies

Implement retry logic with exponential backoff

async function fetchWithRetry(url, options, maxRetries = 3) {
  const RETRYABLE_CODES = [408, 429, 503];

  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      // Return immediately if not a retryable error
      if (!RETRYABLE_CODES.includes(response.status)) {
        return response;
      }

      // Calculate delay: use Retry-After header or exponential backoff
      const retryAfter =
        response.headers.get("Retry-After") || Math.pow(2, i);
      console.log(
        `Retryable error ${response.status}, waiting ${retryAfter}s...`
      );
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    } catch (error) {
      // Network error - retry with backoff
      if (i === maxRetries - 1) throw error;
      await new Promise((resolve) =>
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    }
  }
  throw new Error("Max retries exceeded");
}

Handle payment required errors gracefully
- Redirect users to billing page
- Show clear messaging about credit status
- Provide action buttons for top-up

Caching Recommendations

Cache successful responses to reduce API calls
Respect cache headers if provided
Consider transcript immutability (transcripts rarely change)
Implement cache invalidation for metadata

Rate Limit Management

Monitor X-RateLimit-Remaining header
Implement request queuing when approaching limits
Use exponential backoff on 429 errors
Consider implementing client-side rate limiting

Security

Never expose API keys in client-side code
Store API keys in environment variables
Use backend proxy for browser applications
Rotate API keys regularly
Use separate keys for different environments

Monitoring and Logging

Log all API responses including headers
Monitor credit usage patterns
Track rate limit approaches
Set up alerts for 402 and 429 responses
Monitor response times and cache hit rates

Interactive API Docs (Swagger) Test API endpoints interactively with live requests in your browser.

Getting Started Guide Quick start guide to get up and running with TranscriptAPI.

MCP Integration Use TranscriptAPI with Model Context Protocol for AI workflows.

Need Help?

If you have questions or need assistance:

Visit our Contact page for support options
Manage your account and billing at Billing

YouTube Transcript API Reference

Base URL

Endpoints

Quick Start

Authentication

Request Parameters

video_url (required)

format (optional)

include_timestamp (optional)

send_metadata (optional)

Response Formats

Response Headers

Search Endpoint

Parameters

Response

Channel Endpoints

Resolve Channel

Search Within Channel

Channel Videos (Paginated)

Channel Latest (RSS)

Playlist Endpoint

Credit Usage & Billing

Credit Cost

When Credits Are Charged

Rate Limits

Rate Limit Headers

Best Practices

Error Handling

Retry Strategy

Error Response Format

401 Unauthorized

402 Payment Required

Code Examples

Best Practices

Error Handling Strategies

Caching Recommendations

Rate Limit Management

Security

Monitoring and Logging

Related Resources

Need Help?