Skip to main content
POST
/
youtube
/
transcript
Get transcript for YouTube videos
curl --request POST \
  --url https://api.vidnavigator.com/v1/youtube/transcript \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
  "language": "en",
  "metadata_only": false,
  "fallback_to_metadata": false,
  "transcript_text": false
}
'
{
  "status": "success",
  "data": {
    "video_info": {
      "title": "<string>",
      "description": "<string>",
      "thumbnail": "<string>",
      "url": "<string>",
      "channel": "<string>",
      "channel_url": "<string>",
      "duration": 123,
      "views": 123,
      "likes": 123,
      "published_date": "<string>",
      "keywords": [
        "<string>"
      ],
      "category": "<string>",
      "available_languages": [
        "<string>"
      ],
      "selected_language": "<string>",
      "carousel_info": {
        "total_items": 123,
        "video_count": 123,
        "image_count": 123,
        "selected_index": 123
      }
    },
    "transcript": [
      {
        "text": "<string>",
        "start": 123,
        "end": 123
      }
    ]
  }
}
Extract accurate metadata and transcripts from YouTube videos using residential proxy infrastructure for reliable access.

​
Overview

This endpoint is specifically designed for YouTube videos. Due to YouTube’s bot detection mechanisms, we use residential proxy infrastructure to ensure reliable transcript extraction.
YouTube transcript retrievals consume Residential Proxy Requests because they require residential proxy infrastructure. Check the usage costs page for current pricing.

​
Why a Separate Endpoint?

YouTube has implemented strict bot detection that blocks standard server requests. To maintain reliable access to YouTube transcripts, VidNavigator uses residential proxy infrastructure and bills those calls as residential_request units. This dedicated endpoint allows us to:
  • Provide reliable, consistent access to YouTube transcripts
  • Use optimized infrastructure specifically for YouTube
  • Offer transparent pricing for Residential Proxy Request usage
For non-YouTube videos (TikTok, X/Twitter, Vimeo, etc.), use the standard /transcript endpoint instead.

​
Use Cases

Content Analysis

Extract transcripts for AI analysis, sentiment analysis, or content categorization

Search & Discovery

Enable text-based search across YouTube video content

Accessibility

Generate captions and transcripts for accessibility compliance

Content Creation

Create summaries, articles, or repurpose video content

​
Request Parameters

ParameterTypeRequiredDescription
video_urlstringYesURL of the YouTube video
languagestringNoISO2 language code (e.g., “en”, “es”, “fr”)
metadata_onlybooleanNoWhen true, returns only video metadata without fetching the transcript. Takes precedence over fallback_to_metadata.
fallback_to_metadatabooleanNoWhen true, returns video metadata with an empty transcript if transcript is unavailable (returns 200 instead of 404). Ignored if metadata_only is true.
transcript_textbooleanNoWhen true, returns the transcript as a single plain-text string instead of an array of segments.
Cost-saving tip: Using metadata_only: true bypasses the residential proxy and counts as a Standard Request, making it more cost-effective when you only need video information.

​
Example Usage

curl -X POST "https://api.vidnavigator.com/v1/youtube/transcript" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
    "language": "en"
  }'

​
Getting Metadata Only (Cost-Effective)

If you only need video metadata without the transcript, use metadata_only: true. This bypasses the residential proxy and counts as standard_request usage: 
curl -X POST "https://api.vidnavigator.com/v1/youtube/transcript" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
    "metadata_only": true
  }'

​
Using the SDK

from vidnavigator import VidNavigatorClient, VidNavigatorError

client = VidNavigatorClient()

try:
    result = client.get_youtube_transcript(
        video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        language="en"
    )
    print("Video Title:", result.data.video_info.title)
    print("Available Languages:", result.data.video_info.available_languages)
    for segment in result.data.transcript:
        print(f"[{segment.start:.2f}s - {segment.end:.2f}s] {segment.text}")
except VidNavigatorError as e:
    print(f"An error occurred: {e.message}")

​
Supported URL Formats

This endpoint accepts various YouTube URL formats:
  • https://youtube.com/watch?v=VIDEO_ID
  • https://www.youtube.com/watch?v=VIDEO_ID
  • https://youtu.be/VIDEO_ID
  • https://www.youtube.com/shorts/VIDEO_ID
  • https://m.youtube.com/watch?v=VIDEO_ID

​
Troubleshooting

  • Invalid URL: Ensure the video URL is a valid YouTube URL in one of the supported formats.
  • Transcript Not Found: Please ensure that the video has subtitles available (either manually added or auto-generated). If no subtitles are present, the transcript cannot be extracted. Consider using fallback_to_metadata: true to get metadata even when transcript is unavailable.
  • Language Not Supported: Sometimes the selected subtitles language is not available. Check the available_languages field in the response to see which languages are available.
  • Rate Limit Exceeded: YouTube transcript requests have rate limits. Check your usage and consider upgrading your plan if needed.
If issues persist or you need more help, please reach out to us at support@vidnavigator.com.

​
Success Response (200 OK)

Returns a video_info object and a transcript object. 
{
  "status": "success",
  "data": {
    "video_info": {
      "title": "A Really Cool Video",
      "description": "An example description for the video.",
      "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
      "channel": "Example Creator",
      "channel_url": "https://www.youtube.com/@ExampleCreator",
      "duration": 212.5,
      "views": 123456789,
      "likes": 987654,
      "published_date": "2009-10-25",
      "keywords": ["example", "youtube", "video"],
      "category": "Music",
      "available_languages": ["en", "es", "fr", "de", "ja"],
      "selected_language": "en"
    },
    "transcript": [
      {
        "text": "We're no strangers to love",
        "start": 0.5,
        "end": 3.2
      },
      {
        "text": "You know the rules and so do I",
        "start": 3.5,
        "end": 5.1
      }
    ]
  }
}

​
Response with transcript_text: true

When you set transcript_text: true, the transcript is returned as a single string: 
{
  "status": "success",
  "data": {
    "video_info": { ... },
    "transcript": "We're no strangers to love. You know the rules and so do I."
  }
}

​
Response with metadata_only: true

When you set metadata_only: true, only the video metadata is returned: 
{
  "status": "success",
  "data": {
    "video_info": {
      "title": "A Really Cool Video",
      "description": "An example description for the video.",
      "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
      "channel": "Example Creator",
      "channel_url": "https://www.youtube.com/@ExampleCreator",
      "duration": 212.5,
      "views": 123456789,
      "likes": 987654,
      "published_date": "2009-10-25",
      "keywords": ["example", "youtube", "video"],
      "category": "Music",
      "available_languages": ["en", "es", "fr", "de", "ja"]
    }
  }
}

Authorizations

​
X-API-Key
string
header
required

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Body

application/json
​
video_url
string<uri>
required

URL of the YouTube video

Example:

"https://youtube.com/watch?v=dQw4w9WgXcQ"

​
language
string

ISO2 language code (optional)

Required string length: 2
Example:

"en"

​
metadata_only
boolean
default:false

When true, returns only video metadata without transcript. Usage is counted as a regular transcript request.

​
fallback_to_metadata
boolean
default:false

When true, returns video metadata with an empty transcript if transcript is unavailable (200). Ignored if metadata_only is true.

​
transcript_text
boolean
default:false

When true, returns the transcript as a single plain-text string instead of an array of segments.

Response

Transcript retrieved successfully

​
status
enum<string>
Available options:
success
​
data
object