API Documentation

Access any video transcript programmatically with the Scribe API. Fetch on demand or search across 500k+ cached transcripts.

Get API Key View Pricing

Full-Text Search

Search across 500k+ transcripts with instant results

Bulk Download

Download up to 100 transcripts per request

On-Demand Fetch

Fetch any video transcript on demand, not just pre-indexed ones

Authentication

All API requests require an API key. Include your key in the X-API-Key header.

curl -H "X-API-Key: ytsu_your_api_key_here" \
  "https://api.ytscribe.com/api/v1/search?q=your+query"

Important: Keep your API key secret. Do not share it publicly or commit it to version control.

Base URL

https://api.ytscribe.com/api/v1

All endpoints are relative to this base URL.

Rate Limits

100 requests per minute per API key
Rate limit headers included in responses:

X-RateLimit-Limit: 100

X-RateLimit-Remaining: 95

X-RateLimit-Reset: 1704067200

Endpoints

GET/search

Full-text search across all transcripts in the database.

Query Parameters

q	string, required	Search query
limit	number, optional	Results per page (default: 20, max: 100)
offset	number, optional	Pagination offset (default: 0)
channel	string, optional	Filter by channel ID
minViews	number, optional	Minimum view count

Example Request

curl -H "X-API-Key: $API_KEY" \
  "https://api.ytscribe.com/api/v1/search?q=machine+learning&limit=10"

Example Response

{
  "query": "machine learning",
  "results": [
    {
      "videoId": "aircAruvnKk",
      "title": "But what is a neural network?",
      "channelTitle": "3Blue1Brown",
      "viewCount": 15000000,
      "snippet": "...introduction to <mark>machine learning</mark>...",
      "wordCount": 2500
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1234,
    "hasMore": true
  }
}

GET/transcript/:videoId

Get the full transcript for any video. Fetches directly on demand if not already cached.

Path Parameters

videoId

string, required

Video ID

Query Parameters

lang	string, optional	Language code (default: 'en'). E.g. 'es', 'de', 'ja'
includeMetadata	string, optional	Set to 'true' to include video metadata (title, views, chapters, etc.)

Example Request

curl -H "X-API-Key: $API_KEY" \
  "https://api.ytscribe.com/api/v1/transcript/dQw4w9WgXcQ?lang=en&includeMetadata=true"

Example Response

{
  "videoId": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up",
  "channelTitle": "Rick Astley",
  "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "viewCount": 1726169126,
  "publishedAt": "2009-10-25T00:00:00Z",
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "transcript": {
    "script": "We're no strangers to love...",
    "subs": [
      {"text": "We're no strangers to love", "offset": "18.64", "duration": "3.24"}
    ],
    "language": "English",
    "languageCode": "en",
    "wordCount": 287,
    "duration": 213.5,
    "isGenerated": false
  },
  "cached": false,
  "debug": {
    "method": "innertube-api",
    "usedProxy": false
  },
  "timing": { "totalMs": 1523.45 }
}

On-demand fetching: This endpoint works with any Video ID. If the transcript is not already in our database, it will be fetched directly in real-time and cached for future requests.

POST/transcripts/bulk

Download transcripts for multiple videos in one request (max 100). Fetches on demand for any videos not in the database.

Request Body

videoIds	string[], required	Array of Video IDs (max 100)
fetchMissing	boolean, optional	Fetch from source if not cached (default: true)

{
  "videoIds": ["dQw4w9WgXcQ", "aircAruvnKk", "9bZkp7q19f0"],
  "fetchMissing": true
}

Example Request

curl -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videoIds": ["dQw4w9WgXcQ", "aircAruvnKk"]}' \
  "https://api.ytscribe.com/api/v1/transcripts/bulk"

Example Response

{
  "requested": 2,
  "found": 2,
  "fetched": 1,
  "transcripts": [
    {
      "videoId": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "transcript": { "script": "...", "wordCount": 287 }
    },
    {
      "videoId": "aircAruvnKk",
      "title": "But what is a neural network?",
      "transcript": { "script": "...", "wordCount": 2500 }
    }
  ],
  "timing": { "totalMs": 3241.87 }
}

GET/channels/:channelId/videos

List all indexed videos for a channel with transcript metadata.

Path Parameters

channelId

string, required

Channel ID

Query Parameters

limit	number, optional	Results per page (default: 20, max: 100)
offset	number, optional	Pagination offset (default: 0)

Example Request

curl -H "X-API-Key: $API_KEY" \
  "https://api.ytscribe.com/api/v1/channels/UCuAXFkgsw1L7xaCfnd5JJOw/videos?limit=10"

Example Response

{
  "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "videos": [
    {
      "videoId": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "viewCount": 1726169126,
      "publishedAt": "2009-10-25T00:00:00Z",
      "hasTranscript": true,
      "transcript": {
        "languageCode": "en",
        "wordCount": 287,
        "isGenerated": false
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 42,
    "hasMore": true
  }
}

GET/stats

Get database statistics.

Example Response

{
  "videos": 512345,
  "transcripts": 498234,
  "totalWords": 1234567890,
  "avgWordsPerTranscript": 2478
}

Code Examples

Python

import requests

API_KEY = "ytsu_your_api_key_here"
BASE_URL = "https://api.ytscribe.com/api/v1"

headers = {"X-API-Key": API_KEY}

# Search transcripts
response = requests.get(
    f"{BASE_URL}/search",
    headers=headers,
    params={"q": "machine learning", "limit": 10}
)
results = response.json()

# Get transcript for any video (fetched on demand)
video_id = "dQw4w9WgXcQ"
response = requests.get(
    f"{BASE_URL}/transcript/{video_id}",
    headers=headers,
    params={"lang": "en", "includeMetadata": "true"}
)
transcript = response.json()

# Bulk download (missing videos fetched automatically)
response = requests.post(
    f"{BASE_URL}/transcripts/bulk",
    headers={**headers, "Content-Type": "application/json"},
    json={"videoIds": ["dQw4w9WgXcQ", "aircAruvnKk"]}
)
transcripts = response.json()

JavaScript / Node.js

const API_KEY = "ytsu_your_api_key_here";
const BASE_URL = "https://api.ytscribe.com/api/v1";

// Search transcripts
const response = await fetch(
  `${BASE_URL}/search?q=machine+learning&limit=10`,
  { headers: { "X-API-Key": API_KEY } }
);
const results = await response.json();

// Get transcript for any video (fetched on demand)
const transcript = await fetch(
  `${BASE_URL}/transcript/dQw4w9WgXcQ?lang=en&includeMetadata=true`,
  { headers: { "X-API-Key": API_KEY } }
).then(r => r.json());

// Bulk download (missing videos fetched automatically)
const bulkResponse = await fetch(`${BASE_URL}/transcripts/bulk`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    videoIds: ["dQw4w9WgXcQ", "aircAruvnKk"],
    fetchMissing: true
  })
});
const transcripts = await bulkResponse.json();

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid API key
403	Forbidden - Ultra subscription required or expired
404	Not Found - Resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Need Help?

Have questions or need support? Reach out to us.

[email protected]

Endpoints

GET/search

Full-text search across all transcripts in the database.

Query Parameters

q	string, required	Search query
limit	number, optional	Results per page (default: 20, max: 100)
offset	number, optional	Pagination offset (default: 0)
channel	string, optional	Filter by channel ID
minViews	number, optional	Minimum view count

Example Request

curl -H "X-API-Key: $API_KEY" \
  "https://api.ytscribe.com/api/v1/search?q=machine+learning&limit=10"

Example Response

{
  "query": "machine learning",
  "results": [
    {
      "videoId": "aircAruvnKk",
      "title": "But what is a neural network?",
      "channelTitle": "3Blue1Brown",
      "viewCount": 15000000,
      "snippet": "...introduction to <mark>machine learning</mark>...",
      "wordCount": 2500
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1234,
    "hasMore": true
  }
}

GET/transcript/:videoId

Get the full transcript for any video. Fetches directly on demand if not already cached.

Path Parameters

videoId

string, required

Video ID

Query Parameters

lang	string, optional	Language code (default: 'en'). E.g. 'es', 'de', 'ja'
includeMetadata	string, optional	Set to 'true' to include video metadata (title, views, chapters, etc.)

Example Request

curl -H "X-API-Key: $API_KEY" \
  "https://api.ytscribe.com/api/v1/transcript/dQw4w9WgXcQ?lang=en&includeMetadata=true"

Example Response

{
  "videoId": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up",
  "channelTitle": "Rick Astley",
  "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "viewCount": 1726169126,
  "publishedAt": "2009-10-25T00:00:00Z",
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "transcript": {
    "script": "We're no strangers to love...",
    "subs": [
      {"text": "We're no strangers to love", "offset": "18.64", "duration": "3.24"}
    ],
    "language": "English",
    "languageCode": "en",
    "wordCount": 287,
    "duration": 213.5,
    "isGenerated": false
  },
  "cached": false,
  "debug": {
    "method": "innertube-api",
    "usedProxy": false
  },
  "timing": { "totalMs": 1523.45 }
}

On-demand fetching: This endpoint works with any Video ID. If the transcript is not already in our database, it will be fetched directly in real-time and cached for future requests.

POST/transcripts/bulk

Download transcripts for multiple videos in one request (max 100). Fetches on demand for any videos not in the database.

Request Body

videoIds	string[], required	Array of Video IDs (max 100)
fetchMissing	boolean, optional	Fetch from source if not cached (default: true)

{
  "videoIds": ["dQw4w9WgXcQ", "aircAruvnKk", "9bZkp7q19f0"],
  "fetchMissing": true
}

Example Request

curl -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videoIds": ["dQw4w9WgXcQ", "aircAruvnKk"]}' \
  "https://api.ytscribe.com/api/v1/transcripts/bulk"

Example Response

{
  "requested": 2,
  "found": 2,
  "fetched": 1,
  "transcripts": [
    {
      "videoId": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "transcript": { "script": "...", "wordCount": 287 }
    },
    {
      "videoId": "aircAruvnKk",
      "title": "But what is a neural network?",
      "transcript": { "script": "...", "wordCount": 2500 }
    }
  ],
  "timing": { "totalMs": 3241.87 }
}

GET/channels/:channelId/videos

List all indexed videos for a channel with transcript metadata.

Path Parameters

channelId

string, required

Channel ID

Query Parameters

limit	number, optional	Results per page (default: 20, max: 100)
offset	number, optional	Pagination offset (default: 0)

Example Request

curl -H "X-API-Key: $API_KEY" \
  "https://api.ytscribe.com/api/v1/channels/UCuAXFkgsw1L7xaCfnd5JJOw/videos?limit=10"

Example Response

{
  "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "videos": [
    {
      "videoId": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "viewCount": 1726169126,
      "publishedAt": "2009-10-25T00:00:00Z",
      "hasTranscript": true,
      "transcript": {
        "languageCode": "en",
        "wordCount": 287,
        "isGenerated": false
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 42,
    "hasMore": true
  }
}

GET/stats

Get database statistics.

Example Response

{
  "videos": 512345,
  "transcripts": 498234,
  "totalWords": 1234567890,
  "avgWordsPerTranscript": 2478
}

Code Examples

Python

import requests

API_KEY = "ytsu_your_api_key_here"
BASE_URL = "https://api.ytscribe.com/api/v1"

headers = {"X-API-Key": API_KEY}

# Search transcripts
response = requests.get(
    f"{BASE_URL}/search",
    headers=headers,
    params={"q": "machine learning", "limit": 10}
)
results = response.json()

# Get transcript for any video (fetched on demand)
video_id = "dQw4w9WgXcQ"
response = requests.get(
    f"{BASE_URL}/transcript/{video_id}",
    headers=headers,
    params={"lang": "en", "includeMetadata": "true"}
)
transcript = response.json()

# Bulk download (missing videos fetched automatically)
response = requests.post(
    f"{BASE_URL}/transcripts/bulk",
    headers={**headers, "Content-Type": "application/json"},
    json={"videoIds": ["dQw4w9WgXcQ", "aircAruvnKk"]}
)
transcripts = response.json()

JavaScript / Node.js

const API_KEY = "ytsu_your_api_key_here";
const BASE_URL = "https://api.ytscribe.com/api/v1";

// Search transcripts
const response = await fetch(
  `${BASE_URL}/search?q=machine+learning&limit=10`,
  { headers: { "X-API-Key": API_KEY } }
);
const results = await response.json();

// Get transcript for any video (fetched on demand)
const transcript = await fetch(
  `${BASE_URL}/transcript/dQw4w9WgXcQ?lang=en&includeMetadata=true`,
  { headers: { "X-API-Key": API_KEY } }
).then(r => r.json());

// Bulk download (missing videos fetched automatically)
const bulkResponse = await fetch(`${BASE_URL}/transcripts/bulk`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    videoIds: ["dQw4w9WgXcQ", "aircAruvnKk"],
    fetchMissing: true
  })
});
const transcripts = await bulkResponse.json();

Code

Description

400

Bad Request - Invalid parameters

401

Unauthorized - Missing or invalid API key

403

Forbidden - Ultra subscription required or expired

404

Not Found - Resource not found

429

Too Many Requests - Rate limit exceeded

500

Internal Server Error