# YouTubeAPI.io — Complete LLM & AI Agent Technical Reference (llms-full.txt)

> Real-Time YouTube Transcript, Video Metadata, Comments, Search & Channel Data JSON API.
> Base URL: `https://api.youtubeapi.io` | Main Website: `https://youtubeapi.io`
> OpenAPI 3.1 Spec: `https://youtubeapi.io/openapi.json` | Compact Summary: `https://youtubeapi.io/llms.txt`

## 1. Authentication & Core Architecture

- **Base URL**: `https://api.youtubeapi.io`
- **Authentication Header**: Pass either `x-api-key: yt_live_your_api_key` OR `Authorization: Bearer yt_live_your_api_key` on every request.
- **No Google Cloud OAuth / No 10,000 Quota Cap / No Cloud IP Blocks**: Works directly from AWS, GCP, Azure, Hetzner, Vercel, and Cloudflare Workers without YouTube PO-token blocks or Google compliance audits.
- **Free Trial**: Every new account receives **2,000 Free Credits** immediately upon sign-up at `https://youtubeapi.io/signup`.
- **Zero Charge on Errors or Empty Search**: Any failed lookup, 404 resource, disabled transcript, or empty search result (`items.length === 0`) costs **0 Credits**.

## 2. Pricing & Unified Credit System ($1 = 10,000 Credits)

| Data Type / Endpoint | Credits | Base Cost | Effective Cost with Bonus | Page Size |
| :--- | :--- | :--- | :--- | :--- |
| Timed Transcript, Video Metadata, Channel Profile, Trending | 10 Credits / request | $1.00 / 1,000 requests | $0.40–$0.58 / 1,000 requests | 1 full entity / transcript |
| Video & Shorts Search, Channel Videos & Shorts | 1 Credit / video (min 10) | $0.10 / 1,000 videos | $0.04–$0.06 / 1,000 videos | Up to 50 videos/call |
| Video Comments Feed | 1 Credit / comment (min 10) | $0.10 / 1,000 comments | $0.04–$0.06 / 1,000 comments | Up to 100 comments/call |

## 3. Complete Endpoint Reference & Code Samples

### Extract Timestamped YouTube Video Transcript & Full RAG Text (`GET /v1/youtube/transcript`)
- **Documentation URL**: https://youtubeapi.io/docs/youtube-transcript
- **Cost**: 10 Credits ($0.001)
- **Description**: Fetches full plain-text transcript (`fullTranscriptText`), word count, available subtitle languages, and millisecond-accurate timestamped segments (`segments`) for any YouTube video or Short. Cost: **10 Credits** ($0.001) per video.
- **Parameters**:
  - `video_id` (query, required): 11-character YouTube video ID (`dQw4w9WgXcQ`) or full YouTube watch/Shorts URL (`https://www.youtube.com/watch?v=dQw4w9WgXcQ`). Also accepts `id`, `videoId`, or `url`. 
  - `lang` (query, optional): Preferred ISO 639-1 language code (`en`, `es`, `de`, `fr`, `ja`, `zh-Hans`, etc.). Defaults to `en` with automatic fallback to the primary available track. 
  - `include_segments` (query, optional): Set to `false` to omit the `segments` array and return only `fullTranscriptText` for lightweight LLM context windows. 

```bash
curl "https://api.youtubeapi.io/v1/youtube/transcript?video_id=dQw4w9WgXcQ" \
  -H "x-api-key: yt_live_your_api_key"
```

```python
import requests

res = requests.get(
    "https://api.youtubeapi.io/v1/youtube/transcript?video_id=dQw4w9WgXcQ",
    headers={"x-api-key": "yt_live_your_api_key"},
    timeout=30,
)
print(res.json())
```

---

### Get Full YouTube Video or Shorts Metadata & Engagement Stats (`GET /v1/youtube/video`)
- **Documentation URL**: https://youtubeapi.io/docs/youtube-video
- **Cost**: 10 Credits ($0.001)
- **Description**: Returns rich video metadata including title, full description, views, likes, comment count, duration, publish timestamp, tags/keywords, channel info, and caption availability. Cost: **10 Credits** ($0.001) per video.
- **Parameters**:
  - `video_id` (query, required): 11-character YouTube video ID (`dQw4w9WgXcQ`) or full YouTube URL. Also accepts `id`, `videoId`, or `url`. 

```bash
curl "https://api.youtubeapi.io/v1/youtube/video?video_id=dQw4w9WgXcQ" \
  -H "x-api-key: yt_live_your_api_key"
```

```python
import requests

res = requests.get(
    "https://api.youtubeapi.io/v1/youtube/video?video_id=dQw4w9WgXcQ",
    headers={"x-api-key": "yt_live_your_api_key"},
    timeout=30,
)
print(res.json())
```

---

### Fetch Paginated YouTube Video Comments (Top or Newest) (`GET /v1/youtube/comments`)
- **Documentation URL**: https://youtubeapi.io/docs/youtube-comments
- **Cost**: 10 Credits ($0.001)
- **Description**: Retrieves top or newest comments for a YouTube video, including author handle, channel ID, like count, reply count, pinned/hearted badges, and `nextCursor` pagination token. Cost: **1 Credit per comment returned** (minimum 10 Credits per non-empty call).
- **Parameters**:
  - `video_id` (query, required): 11-character YouTube video ID (`dQw4w9WgXcQ`) or full YouTube URL. 
  - `sort_by` (query, optional): Sort order: `top` (most relevant/liked) or `newest`. 
  - `limit` (query, optional): Number of comments to return per page (1–100). 
  - `cursor` (query, optional): Continuation token from `data.nextCursor` (`meta.next_cursor`). 

```bash
curl "https://api.youtubeapi.io/v1/youtube/comments?video_id=dQw4w9WgXcQ" \
  -H "x-api-key: yt_live_your_api_key"
```

```python
import requests

res = requests.get(
    "https://api.youtubeapi.io/v1/youtube/comments?video_id=dQw4w9WgXcQ",
    headers={"x-api-key": "yt_live_your_api_key"},
    timeout=30,
)
print(res.json())
```

---

### Search YouTube Videos & Shorts by Keyword & Filters (`GET /v1/youtube/search`)
- **Documentation URL**: https://youtubeapi.io/docs/youtube-search
- **Cost**: 10 Credits ($0.001)
- **Description**: Searches YouTube videos and Shorts without the 100-unit quota penalty of official YouTube Data API v3 `search.list`. Supports filtering by `type` (`video` or `shorts`), `sort_by` (`relevance`, `date`, `views`, `rating`), `upload_date`, and `duration`. Cost: **1 Credit per item returned** (minimum 10 Credits per non-empty call).
- **Parameters**:
  - `query` (query, required): Search query string (also accepts `q` or `keyword`). 
  - `type` (query, optional): Filter by content type: `video` or `shorts`. 
  - `sort_by` (query, optional): Sort order: `relevance`, `date`, `views`, or `rating`. 
  - `upload_date` (query, optional): Filter by upload timeframe: `hour`, `today`, `week`, `month`, `year`. 
  - `limit` (query, optional): Maximum number of results to return (1–100). 
  - `cursor` (query, optional): Continuation cursor for next page. 

```bash
curl "https://api.youtubeapi.io/v1/youtube/search?query=ai+agents" \
  -H "x-api-key: yt_live_your_api_key"
```

```python
import requests

res = requests.get(
    "https://api.youtubeapi.io/v1/youtube/search?query=ai+agents",
    headers={"x-api-key": "yt_live_your_api_key"},
    timeout=30,
)
print(res.json())
```

---

### Get YouTube Channel Profile, Subscriber Count & Social Links (`GET /v1/youtube/channel`)
- **Documentation URL**: https://youtubeapi.io/docs/youtube-channel
- **Cost**: 10 Credits ($0.001)
- **Description**: Resolves a YouTube channel by `@handle`, `UC...` channel ID, or full URL and returns subscriber count, total lifetime views, video count, verification status, country, keywords, and external links. Cost: **10 Credits** ($0.001) per call.
- **Parameters**:
  - `handle` (query, optional): YouTube channel handle (e.g. `@MrBeast`, `mrbeast`, or `@googledevelopers`). Provide either `handle`, `channel_id`, or `url`. 
  - `channel_id` (query, optional): YouTube channel ID starting with `UC` (e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`). 

```bash
curl "https://api.youtubeapi.io/v1/youtube/channel" \
  -H "x-api-key: yt_live_your_api_key"
```

```python
import requests

res = requests.get(
    "https://api.youtubeapi.io/v1/youtube/channel",
    headers={"x-api-key": "yt_live_your_api_key"},
    timeout=30,
)
print(res.json())
```

---

### List a YouTube Channel's Uploaded Videos Feed (`GET /v1/youtube/channel/videos`)
- **Documentation URL**: https://youtubeapi.io/docs/youtube-channel-videos
- **Cost**: 10 Credits ($0.001)
- **Description**: Returns paginated long-form videos uploaded by a channel, sorted by `newest`, `popular`, or `oldest`. Cost: **1 Credit per video returned** (minimum 10 Credits per non-empty call).
- **Parameters**:
  - `handle` (query, optional): YouTube channel handle (e.g. `@googledevelopers`). Provide `handle` or `channel_id`. 
  - `channel_id` (query, optional): YouTube channel ID (`UC_x5XG1OV2P6uZZ5FSM9Ttw`). 
  - `sort_by` (query, optional): Sort order: `newest`, `popular`, or `oldest`. 
  - `limit` (query, optional):  
  - `cursor` (query, optional):  

```bash
curl "https://api.youtubeapi.io/v1/youtube/channel/videos" \
  -H "x-api-key: yt_live_your_api_key"
```

```python
import requests

res = requests.get(
    "https://api.youtubeapi.io/v1/youtube/channel/videos",
    headers={"x-api-key": "yt_live_your_api_key"},
    timeout=30,
)
print(res.json())
```

---

### List a YouTube Channel's Shorts Feed (`GET /v1/youtube/channel/shorts`)
- **Documentation URL**: https://youtubeapi.io/docs/youtube-channel-shorts
- **Cost**: 10 Credits ($0.001)
- **Description**: Returns paginated vertical Shorts uploaded by a YouTube channel, sorted by `newest` or `popular`. Cost: **1 Credit per Short returned** (minimum 10 Credits per non-empty call).
- **Parameters**:
  - `handle` (query, optional): YouTube channel handle (e.g. `@MrBeast`). Provide `handle` or `channel_id`. 
  - `channel_id` (query, optional):  
  - `sort_by` (query, optional):  
  - `limit` (query, optional):  
  - `cursor` (query, optional):  

```bash
curl "https://api.youtubeapi.io/v1/youtube/channel/shorts" \
  -H "x-api-key: yt_live_your_api_key"
```

```python
import requests

res = requests.get(
    "https://api.youtubeapi.io/v1/youtube/channel/shorts",
    headers={"x-api-key": "yt_live_your_api_key"},
    timeout=30,
)
print(res.json())
```

---

### Get Trending YouTube Videos by Country & Category (`GET /v1/youtube/trending`)
- **Documentation URL**: https://youtubeapi.io/docs/youtube-trending
- **Cost**: 10 Credits ($0.001)
- **Description**: Fetches currently trending YouTube videos for a 2-letter ISO country code (`US`, `GB`, `JP`, `DE`, `IN`, etc.) and category (`now`, `music`, `gaming`, `movies`). Cost: **Flat 10 Credits** ($0.001) per call.
- **Parameters**:
  - `geo` (query, optional): 2-letter ISO 3166-1 alpha-2 country code. 
  - `type` (query, optional): Trending category (`now`, `music`, `gaming`, `movies`). 
  - `limit` (query, optional):  

```bash
curl "https://api.youtubeapi.io/v1/youtube/trending" \
  -H "x-api-key: yt_live_your_api_key"
```

```python
import requests

res = requests.get(
    "https://api.youtubeapi.io/v1/youtube/trending",
    headers={"x-api-key": "yt_live_your_api_key"},
    timeout=30,
)
print(res.json())
```

## 4. Engineering Guides & Tutorials

### YouTube Transcript API for RAG Pipelines & AI Agents: Complete 2026 Engineering Guide
- **URL**: https://youtubeapi.io/guides/youtube-transcript-api-for-rag-and-llms
- **Summary**: Extract timed YouTube transcripts, plain-text RAG corpora, and multi-language subtitle tracks without datacenter IP blocks or OAuth restrictions.
- **Key Takeaways**:
  - The Official YouTube Data API v3 restricts captions.download strictly to videos you own via OAuth 2.0, making it unusable for third-party AI summarization or RAG pipelines.
  - Self-hosted youtube-transcript-api (Python) and yt-dlp workers running on AWS, GCP, Vercel, or Hetzner datacenter IPs fail with 'Sign in to confirm you're not a bot' and HTTP 429 blocks.
  - YouTubeAPI.io's GET /v1/youtube/transcript endpoint returns both millisecond-accurate timed segments[] and a pre-concatenated full_transcript_text string for $0.001 (10 Credits) per video.
  - 0 Credits are deducted if a video is deleted, private, or has captions disabled.

### Bypassing the YouTube Data API v3 10,000-Unit Daily Quota Limit in Production
- **URL**: https://youtubeapi.io/guides/youtube-data-api-v3-quota-alternative
- **Summary**: Why YouTube Data API v3's 100-unit search.list cost caps developers at 100 searches/day — and how to scale to 600 RPM with YouTubeAPI.io.
- **Key Takeaways**:
  - Google Cloud's default YouTube Data API v3 quota is 10,000 units per day, and each search.list request costs 100 units (maximum 100 searches/day).
  - Requesting a quota increase from Google requires an invasive compliance audit, architecture diagrams, and weeks of waiting with frequent rejections.
  - YouTubeAPI.io provides instant 600 RPM burst capacity across /v1/youtube/search, /v1/youtube/video, and /v1/youtube/channel with zero Google Cloud quota limits.

### Extracting YouTube Video Comments & Audience Sentiment for AI Analysis
- **URL**: https://youtubeapi.io/guides/youtube-comments-scraper-api
- **Summary**: Extract top or newest YouTube video comments with like counts, author handles, and continuation cursors at $0.10 per 1,000 comments.
- **Key Takeaways**:
  - GET /v1/youtube/comments extracts up to 100 comments per call sorted by top or newest.
  - Includes comment_id, author_name, author_channel_id, like_count, reply_count, is_hearted, and is_pinned.
  - Costs 1 Credit per returned comment ($0.10 per 1,000 comments base rate, minimum 10 Credits per non-empty call).

## 5. Competitor Benchmarks

### YouTubeAPI.io vs Official YouTube Data API v3 (developers.google.com/youtube/v3)
- **URL**: https://youtubeapi.io/compare/youtube-data-api-v3
- **Headline**: $1.00 / 1K vs 100 Searches / Day Cap transcripts or video lookups ($0.10/1K search items).
- **Summary**: Google's Official YouTube Data API v3 caps every project at 10,000 quota units/day (charging 100 units per search.list call and 200 units per captions.download call) and blocks downloading transcripts from videos you don't own. YouTubeAPI.io gives you instant REST access to any public video's timed transcript, metadata, comments, search, and channel feeds.

### YouTubeAPI.io vs youtube-transcript-api & yt-dlp (pypi.org/project/youtube-transcript-api)
- **URL**: https://youtubeapi.io/compare/youtube-transcript-api-python
- **Headline**: ~280ms vs Blocked on Cloud IPs from AWS, GCP, Hetzner, Render & Vercel.
- **Summary**: Running youtube-transcript-api or yt-dlp from AWS, GCP, Azure, Hetzner, or Vercel serverless functions triggers YouTube's 'Sign in to confirm you're not a bot' and HTTP 429 walls. YouTubeAPI.io handles residential rotation, timedtext XML/JSON3 parsing, and L1 Redis caching behind a simple HTTPS endpoint.

### YouTubeAPI.io vs Apify YouTube Scrapers (apify.com)
- **URL**: https://youtubeapi.io/compare/apify-youtube-scrapers
- **Headline**: $0.10–$1.00 vs $2.50–$5.00+ per 1,000 items or transcripts.
- **Summary**: Container-based scraping platforms spin up a Docker actor per job, adding 20–60 seconds of cold-start latency and charging platform compute markups. YouTubeAPI.io is an always-hot REST gateway with L1 Redis caching that responds in ~250ms.

## 6. Frequently Asked Questions

### How does the Unified Credit System work?

$1 equals 10,000 Credits (1 Credit = $0.0001). Single entity & transcript lookups (/v1/youtube/transcript, /v1/youtube/video, /v1/youtube/channel, /v1/youtube/trending) cost 10 Credits ($1.00 / 1,000 requests). List endpoints (/v1/youtube/search, /v1/youtube/comments, /v1/youtube/channel/videos, /v1/youtube/channel/shorts) deduct 1 Credit per returned item ($0.10 / 1,000 items) with a minimum floor of 10 Credits ($0.001) per non-empty response.

### Do I need a Google Cloud Project, OAuth 2.0 consent screen, or 10,000-unit quota audit?

No. Unlike the Official YouTube Data API v3—which caps every project at 10,000 units/day (only 100 search.list calls per day!), blocks public caption track downloads via captions.download unless you own the channel, and requires weeks of Google compliance audits—YouTubeAPI.io works immediately with a single x-api-key: yt_live_... header.

### How does /v1/youtube/transcript return timed captions and RAG-ready plain text?

GET /v1/youtube/transcript?video_id=dQw4w9WgXcQ&lang=en returns both a millisecond-accurate segments[] array ({ text, offset_ms, duration_ms, start_seconds }) AND a pre-concatenated full_transcript_text string ready for LLM prompts, LangChain, LlamaIndex, or vector embeddings, plus available_languages[] for multi-language discovery.

### Am I charged when a request fails, returns 404, or a video has captions disabled?

Never. We strictly enforce Charge-Before-Return & Zero-Charge on Error/Empty: only HTTP 200 responses with non-empty data deduct credits. Upstream errors, deleted/private videos (HTTP 404), videos with disabled transcripts, rate-limited requests (HTTP 429), and empty search results cost 0 Credits.

### Should I choose a Monthly Plan or Pay-As-You-Go (One-Time Top-Up)?

Both credit your account with the exact same bonus credit packages (Starter 250,000 Credits, Pro 1,200,000 Credits, Business 5,000,000 Credits). Pay-As-You-Go top-ups have no recurring billing and your purchased credit balance never expires. Monthly subscriptions save up to 24% more for continuous AI video ingestion and channel monitoring workloads.

### What are the concurrency, pagination, and RPM rate limits?

Free Trial accounts include 2,000 Credits, 30 RPM, and full access to all 8 endpoints for evaluation. Paid accounts unlock unlimited deep continuation token pagination and scale from 120 RPM (Starter) and 600 RPM (Pro) up to 600 RPM (Business).

### What payment methods are accepted?

You can top up or subscribe instantly with 0%-fee Cryptocurrency via NOWPayments (USDT or USDC on Solana, Tron, Polygon, Arbitrum, BNB Smart Chain, and Ethereum, plus BTC, ETH, and SOL) with an automatic +5% bonus credit reward.

### Can I use YouTubeAPI.io inside Claude Desktop, Cursor, or LangChain?

Yes. Configure our MCP Server in Claude Desktop, Cursor, or Windsurf using your yt_live_... API key to give AI agents real-time YouTube video transcript extraction, semantic video search, channel feed analysis, and comment sentiment tools.

### How does YouTubeAPI.io compare to youtube-transcript-api (Python) and yt-dlp?

Running youtube-transcript-api or yt-dlp from AWS, GCP, Hetzner, or Vercel datacenter IPs triggers YouTube's 'Sign in to confirm you're not a bot' PO-token and HTTP 429 blocks. YouTubeAPI.io handles residential proxy rotation, multi-key pool failover, L1 Redis caching, and permanent PostgreSQL 16 storage behind a sub-250ms REST endpoint.

### Is YouTubeAPI.io affiliated with YouTube or Google LLC?

No. YouTubeAPI.io is an independent developer infrastructure provider for publicly available web data and is not affiliated with, endorsed by, or sponsored by YouTube or Google LLC.

### How much does it cost to extract 10,000 YouTube transcripts or 100,000 comments?

At 10 Credits per transcript ($1.00 / 1,000 transcripts) and 1 Credit per comment ($0.10 / 1,000 comments, up to 100 comments or 50 search videos per call), 10,000 full transcripts or 100,000 comments cost $10.00 base PAYG (or $5.75 effective on the Pro plan and $3.98 effective on the Business plan).

### What is your refund policy?

Payments made within the last 30 days can be refunded up to the unused purchased balance on your account. Promotional signup credits have no cash value.