YouTube transcript API
Retrieve existing public YouTube caption tracks through one authenticated GET request, with full text, language, and timed JSON segments for your application.
- One REST Endpoint
- Structured JSON Output
- Timed Caption Segments
- Preferred Language Selection
- Safe Idempotent Retries
- Caption Availability Signals
Request examples
curl "https://api.agentbody.io/v1/youtube/transcript?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ&language=en" \
-H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>"Response examples
Documented responses from the OpenAPI specification.
Existing captions or explicitly requested audio transcription.
{
"caption_type": "manual",
"language": "example_value",
"segments": [],
"text": "example_value",
"video_id": "example_value"
}Features
Use the YouTube Transcript API to retrieve existing public caption tracks as structured JSON for research pipelines, video-aware products, retrieval workflows, and content analysis.
One REST Endpoint
Call GET /v1/youtube/transcript with a bearer API key and a public video URL. The YouTube transcript API returns an existing caption track through a documented HTTP request, so applications can add caption retrieval without maintaining a browser-driven workflow or a separate client SDK.
Structured JSON Output
Receive caption_type, language, video_id, complete transcript text, and timed segments in a predictable JSON response. This structure is useful when your service needs to store captions, index text, create video-aware search, or pass transcript data into an analysis pipeline.
Timed Caption Segments
Each segment includes caption text with start and end timing information. Use these timed segments to link a search result, quote, note, or generated reference back to the relevant moment in the original public video instead of treating the transcript as an unstructured block of text.
Preferred Language Selection
Pass the optional language parameter to request a preferred public caption language, such as en or zh. The API reads caption tracks that are available for the submitted video; it does not create a translation or a language track that the video does not publish.
Safe Idempotent Retries
Send an idempotency key when your application needs retry protection. A repeated request with the same key replays the stored response rather than creating another billable execution, helping background jobs and webhooks recover from uncertain network outcomes without duplicate processing.
Caption Availability Signals
When a public video has no available caption track, the YouTube API for getting transcript data returns 422 rather than inventing text. Treat that response as a final availability signal for the unchanged URL, select another resource, or use a separately approved fallback workflow.
How to use
Follow these six steps to call the YouTube Transcript API, select a public caption language, and process transcript text with timed segments in your own application.
Create An API Key
Create an AgentBody account and generate an API key in the console. Keep the key in your server environment or approved secret store, then use it as a bearer token for requests. Do not put a live key in browser code, public repositories, or client-side bundles.
Choose A Public Video
Choose the exact public YouTube video whose existing captions you need. Copy its complete URL and verify that it is accessible. Private, unavailable, or captionless videos cannot return a transcript, so prepare an alternate public resource when your workflow needs coverage for unavailable caption tracks.
Build The GET Request
Send an authenticated GET request to /v1/youtube/transcript with the URL query parameter. The generated examples on this page show the request in curl, JavaScript, Python, Java, and Go, so you can adopt the language and HTTP client used by your service.
Select A Language
Add the optional language parameter when you want a preferred caption language. Use a BCP 47 tag such as en or zh. The request can only return a caption track publicly available for the submitted video, not a new translated track or an unavailable language.
Parse The JSON Response
Read the returned language, complete text, and segments in your application. Preserve segment timing when you need traceable quotes, timestamped search results, study notes, or RAG context. Store only the fields your product needs and keep the response handling aligned with your own privacy policy.
Handle 422 Correctly
If the API returns 422, the video has no available public caption track. Do not retry the unchanged URL, because the response is not a temporary failure. Select another public resource or obtain approval before invoking a separate, billed transcription workflow for that video.
Frequently asked questions
What is the YouTube Transcript API?
The YouTube Transcript API is an authenticated GET endpoint for retrieving an existing public caption track from a YouTube video. Send a public video URL and optionally a preferred language. A successful response provides caption metadata, complete text, and timed segments as JSON, which your application can process for search, research, notes, or video-aware workflows.
Is there a way to get transcript of YouTube video from their API?
Yes. Send a bearer-authenticated request to GET /v1/youtube/transcript with a public YouTube video URL. The API retrieves an existing public caption track when one is available and returns structured JSON. It does not create captions for a video with no public track, so handle a 422 response by selecting another resource rather than retrying unchanged.
Can I use this YouTube API for getting transcript data in another language?
Yes. Add the optional language query parameter with a BCP 47 value such as en or zh to request a preferred caption language. The YouTube transcript API can only return public tracks available on that specific video. It does not translate captions or generate a language track that the source video does not provide.
What data does the youtube-transcript-api return?
A successful youtube-transcript-api response includes caption_type, language, video_id, the complete transcript text, and timed segments. Segment timing lets your application tie extracted text to the corresponding moment in the original video. Use the JSON fields directly in storage, search, research, or analysis workflows without depending on a browser-rendered transcript page.
How should I handle youtube_transcript_api errors?
Correct 400 responses by fixing the request and 401 responses by configuring a valid API key. A 422 response means the submitted video has no available public caption track, so do not retry the same URL unchanged. For temporary 502, 503, or 504 failures, retry with backoff and report temporary unavailability if the request remains unsuccessful.
Do idempotent retries create a second charge?
No. Include an idempotency key with the request when your application may retry after a network interruption. The gateway replays the stored response for the same key rather than executing the same request again. This gives youtubetranscriptapi integrations a controlled retry path while preserving the original result and avoiding duplicate billable processing.