YouTube Transcript API Reference

The Scority Transcript API exposes one protected endpoint:GET /v1/youtube/transcript. It works with many public YouTube videos that have accessible captions; it does not guarantee transcripts for every video.

API base URL: https://api.scority.ai. Machine-readable OpenAPI is available at https://api.scority.ai/openapi.json. The human guide for importing that spec is /docs/openapi.

Endpoint

GET /v1/youtube/transcript

Query parameters

video_id: YouTube video ID. Either video_id or video_url is required. Sending both returns ambiguous_request.
video_url: Full YouTube URL. Cannot be combined with video_id. Malformed URLs return invalid_video_url.
language: Optional language code such as en, en-US, ru, or ru-RU. See language options.
lang: Alias for language. Cannot be combined with language.

Authentication

Send your Scority API key with the x-api-key header. Keep the key server-side. Do not expose it in browser code, mobile apps, public repositories, or screenshots.

curl

curl "https://api.scority.ai/v1/youtube/transcript?video_id=dQw4w9WgXcQ&language=en" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://api.scority.ai/v1/youtube/transcript?video_id=dQw4w9WgXcQ&language=en" \
  -H "x-api-key: YOUR_API_KEY"

request.sh2 lines

Responses

Response shape

200 response

{
  "language": "en",
  "source": "captions",
  "text": "Never gonna give you up...",
  "segments": [
    {
      "text": "Never gonna give you up",
      "start": 18.2,
      "duration": 2.1
    }
  ]
}

{
  "language": "en",
  "source": "captions",
  "text": "Never gonna give you up...",
  "segments": [
    {
      "text": "Never gonna give you up",
      "start": 18.2,
      "duration": 2.1
    }
  ]
}

response.json12 lines

error response

{
  "error": {
    "code": "transcript_not_available",
    "message": "Transcript is not available for this video."
  }
}

{
  "error": {
    "code": "transcript_not_available",
    "message": "Transcript is not available for this video."
  }
}

error.json6 lines

The public response intentionally omits cache internals, API key identifiers, proxy details, diagnostics, caption track URLs, and upstream response bodies.

Errors

Error codes

On small screens, errors are shown as cards so each code, status and action stays readable without horizontal dragging.

UNAUTHORIZED

Missing or invalid API key.

invalid_video_id

The video_id is not a valid YouTube video ID.

invalid_video_url

The video_url is not a valid YouTube URL.

ambiguous_request

video_id and video_url were missing or both provided.

invalid_language

language/lang is malformed or too long.

ambiguous_language

language and lang were both provided.

transcript_not_available

No accessible captions were found.

upstream_transcript_failed

YouTube/upstream transcript fetch failed.

quota_exceeded

The monthly quota for this key has been reached.

rate_limited

The request exceeded the current rate limit.

rate_limit_unavailable

Rate limit store is unavailable when fail-closed mode is enabled.

transcript_fetch_failed

Unexpected transcript fetch failure.

Code	Meaning
UNAUTHORIZED	Missing or invalid API key.
invalid_video_id	The video_id is not a valid YouTube video ID.
invalid_video_url	The video_url is not a valid YouTube URL.
ambiguous_request	video_id and video_url were missing or both provided.
invalid_language	language/lang is malformed or too long.
ambiguous_language	language and lang were both provided.
transcript_not_available	No accessible captions were found.
upstream_transcript_failed	YouTube/upstream transcript fetch failed.
quota_exceeded	The monthly quota for this key has been reached.
rate_limited	The request exceeded the current rate limit.
rate_limit_unavailable	Rate limit store is unavailable when fail-closed mode is enabled.
transcript_fetch_failed	Unexpected transcript fetch failure.

Limits

Rate limits and quotas

API keys use short-window rate limits and monthly quota controls. Successful transcript responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Short-window throttling returns 429 rate_limited with Retry-After. Monthly quota exhaustion returns 429 quota_exceeded.

Examples

Server-side examples

server-side fetch

const response = await fetch(
  "https://api.scority.ai/v1/youtube/transcript?video_id=dQw4w9WgXcQ",
  {
    headers: { "x-api-key": process.env.SCORITY_API_KEY! },
  },
)

const result = await response.json()

const response = await fetch(
  "https://api.scority.ai/v1/youtube/transcript?video_id=dQw4w9WgXcQ",
  {
    headers: { "x-api-key": process.env.SCORITY_API_KEY! },
  },
)

const result = await response.json()

transcript.ts8 lines

requests

import os
import requests

response = requests.get(
    "https://api.scority.ai/v1/youtube/transcript",
    params={"video_id": "dQw4w9WgXcQ", "language": "en"},
    headers={"x-api-key": os.environ["SCORITY_API_KEY"]},
    timeout=30,
)
result = response.json()

import os
import requests

response = requests.get(
    "https://api.scority.ai/v1/youtube/transcript",
    params={"video_id": "dQw4w9WgXcQ", "language": "en"},
    headers={"x-api-key": os.environ["SCORITY_API_KEY"]},
    timeout=30,
)
result = response.json()

transcript.py10 lines

You can also import the OpenAPI document into Postman, Insomnia, Scalar, or another API client from https://api.scority.ai/openapi.json.

Guides

Related implementation guides

YouTube API transcript guideRead the guide →Captions and subtitlesRead the guide →API key guideRead the guide →Quota and rate limitsRead the guide →Error troubleshootingRead the guide →Python guideRead the guide →Node.js guideRead the guide →JavaScript guideRead the guide →Without OAuthRead the guide →Quota exceededRead the guide →Language optionsRead the guide →OpenAPI specificationRead the guide →