The curl Cheat Sheet for the YouTube Transcript API

curl is the fastest way to confirm an API actually works before you write a single line of application code. This post gives you a ready-to-run curl command for every core endpoint in the YouTube Transcript API, plus patterns for piping JSON through jq, decoding error responses, and turning working one-liners into reusable scripts.

Set your token once, use it everywhere

Every authenticated request to the YouTube Transcript API requires an Authorization header with your Bearer token. Export it as an environment variable at the start of each terminal session so you never paste it directly into a command:

export YT_TOKEN="your_api_key_here"

Every curl command in this post references $YT_TOKEN. If you see a 401 Unauthorized response, the most common cause is that the variable is not set in the current shell.

Fetching a transcript

The core endpoint is /api/v2/transcript. Pass either a bare video ID or a full YouTube URL to the video_url parameter:

# Using a bare video ID
curl "https://getyoutubetranscriber.com/api/v2/transcript?video_url=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YT_TOKEN"

# Using a full URL (URL-encode the & if your shell requires it)
curl "https://getyoutubetranscriber.com/api/v2/transcript?video_url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YT_TOKEN"

The response is a JSON object with a transcript array. Each element has text, start, and duration fields:

{
  "transcript": [
    { "text": "Never gonna give you up", "start": 43.2, "duration": 2.1 },
    { "text": "Never gonna let you down", "start": 45.3, "duration": 2.0 }
  ]
}

To request a specific language, add a lang parameter. The API covers 125+ languages:

curl "https://getyoutubetranscriber.com/api/v2/transcript?video_url=dQw4w9WgXcQ&lang=es" \
  -H "Authorization: Bearer $YT_TOKEN"

For a deeper look at how auto-generated and manually uploaded captions differ in practice, see the YouTube Captions API: Auto vs Manual Captions Explained post.

Bulk transcripts in one POST

When you need transcripts for multiple videos, avoid looping over single-video requests. The /api/v2/transcripts-bulk endpoint accepts up to 50 IDs in one POST body:

curl -X POST "https://getyoutubetranscriber.com/api/v2/transcripts-bulk" \
  -H "Authorization: Bearer $YT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"video_urls": ["dQw4w9WgXcQ", "9bZkp7q19f0", "kJQP7kiw5Fk"]}'

This is the right pattern for ETL pipelines and dataset builds where you are pulling hundreds of videos from a playlist or channel list.

Searching YouTube from the terminal

The /api/v2/search endpoint runs a keyword search across YouTube and returns video metadata:

curl "https://getyoutubetranscriber.com/api/v2/search?q=machine+learning+tutorial" \
  -H "Authorization: Bearer $YT_TOKEN"

Use this to discover video IDs programmatically before you pull their transcripts, rather than hard-coding IDs.

Resolving a channel handle (no token needed)

/api/v2/channel-resolve accepts an @handle, a channel URL, or a channel ID and returns the canonical channel ID. This endpoint is free and requires no Bearer token:

curl "https://getyoutubetranscriber.com/api/v2/channel-resolve?channel=@MrBeast"

This is useful at the start of any channel-monitoring workflow, where you need to normalize user-supplied handles into stable IDs before making subsequent authenticated calls. See the Resolve YouTube Channel Handles to IDs via API post for more on that pattern.

Listing and searching a channel's videos

Once you have a channel ID, two endpoints let you work with its uploads.

List all channel videos (paginated with a continuation token):

curl "https://getyoutubetranscriber.com/api/v2/channel/videos?channel=UCX6OQ3DkcsbYNE6H8uQQuVA" \
  -H "Authorization: Bearer $YT_TOKEN"

Search within a specific channel:

curl "https://getyoutubetranscriber.com/api/v2/channel/search?channel=UCX6OQ3DkcsbYNE6H8uQQuVA&q=react+hooks" \
  -H "Authorization: Bearer $YT_TOKEN"

For the next page, take the continuation value from the response and pass it back:

curl "https://getyoutubetranscriber.com/api/v2/channel/videos?channel=UCX6OQ3DkcsbYNE6H8uQQuVA&continuation=TOKEN_HERE" \
  -H "Authorization: Bearer $YT_TOKEN"

Checking new uploads via RSS (free)

/api/v2/channel-latest polls YouTube's public RSS feed and returns the most recent uploads for a channel. No token required:

curl "https://getyoutubetranscriber.com/api/v2/channel-latest?channel=UCX6OQ3DkcsbYNE6H8uQQuVA"

This is a low-cost polling endpoint for cron jobs that watch for new content without burning credits on full channel video listings.

Fetching playlist videos

To retrieve all videos in a playlist in order:

curl "https://getyoutubetranscriber.com/api/v2/playlist-videos?playlist_id=PLrAXtmErZgOeiKm4sgNOknc9TTnLs_oL" \
  -H "Authorization: Bearer $YT_TOKEN"

Combine this with the bulk transcript endpoint: pull the playlist, extract video IDs with jq, then POST them in batches of 50.

Piping through jq

Raw JSON from curl is difficult to scan. Install jq (available on every major OS) and pipe output through it for instant readability.

Print the full response, pretty-printed:

curl -s "https://getyoutubetranscriber.com/api/v2/transcript?video_url=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YT_TOKEN" | jq .

Extract only the plain text from each transcript segment and join them into a single string:

curl -s "https://getyoutubetranscriber.com/api/v2/transcript?video_url=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YT_TOKEN" \
  | jq '[.transcript[].text] | join(" ")'

Extract just the first 5 segments to confirm the shape of the data:

curl -s "https://getyoutubetranscriber.com/api/v2/transcript?video_url=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YT_TOKEN" \
  | jq '.transcript[:5]'

Pull video IDs from a playlist response into a plain list, ready to feed into another command:

curl -s "https://getyoutubetranscriber.com/api/v2/playlist-videos?playlist_id=PL_ID" \
  -H "Authorization: Bearer $YT_TOKEN" \
  | jq -r '.videos[].videoId'

The -s flag suppresses curl's progress meter, keeping the output clean for piping.

Debugging errors fast

The API uses standard HTTP status codes. Add -w "\nHTTP %{http_code}\n" to any curl command to print the status code after the body:

curl -s -w "\nHTTP %{http_code}\n" \
  "https://getyoutubetranscriber.com/api/v2/transcript?video_url=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YT_TOKEN"

401 Unauthorized. Your token is missing, misspelled, or revoked. Confirm echo $YT_TOKEN returns something. If the variable is set but the call still fails, log into getyoutubetranscriber.com to verify the key is active.

402 Payment Required. You have exhausted your credits. The free tier starts with 100 credits. Check your account dashboard, then either top up or review whether you are calling the API in a loop without a cache.

404 Not Found. For the transcript endpoint, this most often means the video has captions disabled or has been removed. Your script should catch 404 and log the video ID rather than retrying. See Handle Missing YouTube Transcripts Gracefully for a complete handling pattern.

429 Too Many Requests. You are hitting a rate limit. Add an exponential back-off with sleep between retries, or use the bulk endpoint to reduce request count.

5xx errors. Transient server errors. Retry after a short delay with --retry 3 --retry-delay 2 in your curl flags.

For verbose connection details (TLS handshake, headers, timing), add -v to any curl command:

curl -v "https://getyoutubetranscriber.com/api/v2/transcript?video_url=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YT_TOKEN" 2>&1 | head -50

Turning one-liners into scripts

Once a curl command works interactively, wrapping it in a shell script takes about 30 seconds. Here is a minimal transcript-fetching script with basic error handling:

#!/usr/bin/env bash
# fetch_transcript.sh <video_id>

set -euo pipefail

VIDEO_ID="${1:?Usage: $0 <video_id>}"
BASE="https://getyoutubetranscriber.com/api/v2"

response=$(curl -s -w "\n%{http_code}" \
  "${BASE}/transcript?video_url=${VIDEO_ID}" \
  -H "Authorization: Bearer ${YT_TOKEN}")

http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | head -n-1)

if [[ "$http_code" != "200" ]]; then
  echo "Error ${http_code}: ${body}" >&2
  exit 1
fi

echo "$body" | jq '[.transcript[].text] | join(" ")'

Run it with:

chmod +x fetch_transcript.sh
./fetch_transcript.sh dQw4w9WgXcQ

The same pattern extends to bulk jobs: read a file of video IDs, build a JSON array, POST to /api/v2/transcripts-bulk in batches, and write each transcript to a separate file. The curl --data @filename flag lets you pass a pre-built JSON file instead of constructing the body inline.

Quick reference table

| Endpoint | Method | Auth | One-liner | |--|--|--|--| | /api/v2/transcript | GET | Required | curl "…?video_url=ID" -H "Authorization: Bearer $YT_TOKEN" | | /api/v2/transcripts-bulk | POST | Required | curl -X POST … -d '{"video_urls":[…]}' | | /api/v2/search | GET | Required | curl "…?q=QUERY" -H "Authorization: Bearer $YT_TOKEN" | | /api/v2/channel-resolve | GET | Free | curl "…?channel=@handle" | | /api/v2/channel/videos | GET | Required | curl "…?channel=ID" -H "Authorization: Bearer $YT_TOKEN" | | /api/v2/channel/search | GET | Required | curl "…?channel=ID&q=QUERY" -H "Authorization: Bearer $YT_TOKEN" | | /api/v2/channel-latest | GET | Free | curl "…?channel=ID" | | /api/v2/playlist-videos | GET | Required | curl "…?playlist_id=ID" -H "Authorization: Bearer $YT_TOKEN" |

What to do next

If these commands work in your terminal, the next step is integrating them into your application. The API is hosted at https://getyoutubetranscriber.com and all endpoints accept standard HTTP, so any HTTP client in any language can replace curl directly. Start with the API docs if you need request and response schemas beyond what is shown here, and claim your 100 free credits to run these commands against real videos without a credit card.