youtube-data-api · diff
v3.0.0 to v3.0.0
18 added, 4 removed. Audit A to A.
---
name: youtube-data-api
- description: "YouTube data API: search videos, Shorts and channels, then pull video metadata, comments and replies, transcripts, related videos, download streams, and channel info, videos and community posts. Returns title, view count, duration, published time, channel and caption fields as JSON. 15 endpoints, 1-8 credits each."
+ description: "YouTube data API: search videos, Shorts and channels, then pull video metadata, comments and replies, transcripts, related videos, download streams, channel info, videos and community posts, and a single community post with its comments. Returns title, view count, duration, published time, channel and caption fields as JSON. 17 endpoints, 1-5 credits each."
version: 3.0.0
tags: youtube, youtube-api, youtube-data-api, video-search, transcripts, captions, comments, channels, shorts, video-metadata, content-research, rag, langchain, crewai, autogen, structured-data, json, ai-agents
metadata:
openclaw:
requires:
env:
- SCAVIO_API_KEY
primaryEnv: SCAVIO_API_KEY
timeout: 90
throttle: 1
emoji: "▶"
homepage: https://scavio.dev/docs?utm_source=agent-skills&utm_medium=skill&utm_campaign=youtube-data-api
---
# YouTube Data API - Search, Videos, Comments, Transcripts, Channels
- Search YouTube and retrieve videos, shorts, search suggestions, video metadata, comments, transcripts, related videos, download streams, and full channel data (info, videos, shorts, community posts). All endpoints return structured JSON.
+ Search YouTube and retrieve videos, shorts, search suggestions, video metadata, comments, transcripts, related videos, download streams, full channel data (info, videos, shorts, community posts), and a single community post with its comments. All endpoints return structured JSON.
## When to trigger
Use this skill when the user asks to:
- Find YouTube videos, shorts, or channels on a topic
- Get a video's metadata, view count, duration, or captions list
- Read a video's comments and comment replies
- Pull a full transcript or timed subtitles for a video
- Get related videos or direct download stream URLs
- Look up a channel's info, videos, shorts, or community posts
- Resolve a channel handle or URL to a channel ID
+ - Read one community post by id or URL, or the comments under it
## Setup
Get a free API key at [scavio.dev](https://scavio.dev/?utm_source=agent-skills&utm_medium=skill&utm_campaign=youtube-data-api) (50 free credits to get started, no card required):
```bash
export SCAVIO_API_KEY=sk_live_your_key
```
### If you do not have a key yet
An agent running this skill without `SCAVIO_API_KEY` set will get `401` on every
call below. The whole path from nothing to a working key is self-serve:
1. Sign up at [dashboard.scavio.dev](https://dashboard.scavio.dev/sign-up?utm_source=agent-skills&utm_medium=skill&utm_campaign=youtube-data-api) - email or Google, no card required.
2. A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy.
3. A new account starts with 50 credits. Endpoints in this skill cost 1 credit each unless the table below says otherwise.
When the balance runs out the API answers `402` with a JSON body carrying
`billing_url`. Topping up needs no code change - the same key keeps working.
The smallest purchase is 2,500 credits for $25, and monthly plans work out
cheaper per credit if the usage is steady rather than one-off.
Every request is a `POST` with a JSON body and:
```
Authorization: Bearer $SCAVIO_API_KEY
```
## Endpoints
Base URL: `https://api.scavio.dev`. All paths are under `/api/v1/youtube`.
### Video endpoints
| Endpoint | Credits | Description |
|---|---|---|
| `POST /api/v1/youtube/search` | 2 | Search videos (and channels/playlists) |
| `POST /api/v1/youtube/shorts` | 2 | Search Shorts |
| `POST /api/v1/youtube/suggestions` | 1 | Search autocomplete suggestions |
| `POST /api/v1/youtube/video` | 1 | Full video metadata and captions list |
| `POST /api/v1/youtube/comments` | 1 | Top-level comments for a video |
| `POST /api/v1/youtube/comments/replies` | 1 | Replies to a specific comment |
- | `POST /api/v1/youtube/transcript` | 8 | Full transcript or timed subtitles |
+ | `POST /api/v1/youtube/transcript` | 5 | Full transcript or timed subtitles |
| `POST /api/v1/youtube/related` | 1 | Videos related to a video |
| `POST /api/v1/youtube/streams` | 3 | Direct playable/downloadable stream URLs |
### Channel endpoints
| Endpoint | Credits | Description |
|---|---|---|
| `POST /api/v1/youtube/channel/search` | 1 | Search channels |
| `POST /api/v1/youtube/channel` | 1 | Full channel info |
| `POST /api/v1/youtube/channel/videos` | 1 | A channel's videos |
| `POST /api/v1/youtube/channel/shorts` | 1 | A channel's Shorts |
| `POST /api/v1/youtube/channel/community` | 1 | A channel's community posts |
| `POST /api/v1/youtube/channel/resolve` | 1 | Resolve a handle or URL to a channel ID |
+ | `POST /api/v1/youtube/community/post` | 1 | One community post by id or URL |
+ | `POST /api/v1/youtube/community/post/comments` | 1 | Comments on a community post |
> `POST /api/v1/youtube/metadata` still works as a **deprecated alias** of `/video`. Use `/video` for new code.
## Workflow
1. **Find a video:** call `/search` with `search`. Use `sort_by: view_count` for the most-watched result. Read `results[].video_id`.
2. **Get metadata:** call `/video` with `video_id` (accepts a full watch URL too) for description, `length_seconds`, `view_count`, `keywords`, and `captions[]`.
3. **Read discussion:** call `/comments`, then `/comments/replies` with a comment's `reply_cursor` to expand a thread.
4. **Get the text:** call `/transcript` for a plain transcript (`format: text`) or timed subtitles (`format: srt`).
5. **Download:** call `/streams` for direct format URLs.
6. **Channels:** resolve a handle with `/channel/resolve`, then call `/channel`, `/channel/videos`, `/channel/shorts`, or `/channel/community`.
+ 7. **Community posts:** take a `post_id` from `/channel/community` (or a post URL), call `/community/post` for the post, then `/community/post/comments` with the same `post_id` (optionally `cursor: comments_cursor`) for its comments.
Paginated endpoints return `next_cursor` and `has_more`; pass `next_cursor` back as `cursor` for the next page.
## Parameters
### Search (`/search`)
| Parameter | Type | Default | Description |
|---|---|---|---|
| `search` | string | required | Search query — note: this field is `search`, not `query` |
| `upload_date` | string | -- | `last_hour`, `today`, `this_week`, `this_month`, `this_year` |
| `type` | string | -- | `video`, `channel`, `playlist`, or `movie` |
| `duration` | string | -- | `short`, `medium`, `long` |
| `sort_by` | string | `relevance` | `relevance`, `date`, `view_count`, `rating` |
| `features` | string[] | -- | Any of `hd`, `4k`, `subtitles`, `creative_commons`, `live`, `360`, `3d`, `hdr`, `vr180` |
| `cursor` | string | -- | Pagination cursor from a prior `next_cursor` |
Legacy boolean flags (`subtitles`, `creative_commons`, `hd`, `4k`, `live`, `360`, `3d`, `hdr`, `vr180`) are still accepted for backward compatibility; prefer the `features` array.
### Shorts (`/shorts`)
`search`* , `sort_by`, `cursor`.
### Suggestions (`/suggestions`)
`search`* , `language` (default `en`), `region` (default `US`).
### Video (`/video`) and metadata alias
`video_id`* — accepts a raw ID or a full watch URL.
### Comments (`/comments`)
`video_id`* , `cursor`.
### Comment replies (`/comments/replies`)
`video_id`* , `reply_cursor`* (a comment's `reply_cursor`), `cursor`.
### Transcript (`/transcript`)
`video_id`* , `language` (default `en`), `format` (`text` for plain, `srt` for timed; default `text`).
### Related (`/related`)
`video_id`* , `cursor`.
### Streams (`/streams`)
`video_id`* .
### Channel search (`/channel/search`)
`search`* , `cursor`.
### Channel (`/channel`)
`channel_id`* — accepts a channel ID, `@handle`, or channel URL.
### Channel videos / shorts / community
`channel_id`* , `cursor`.
### Channel resolve (`/channel/resolve`)
`channel`* — a `@handle` or channel URL. Returns `channel_id` and `channel_url`.
+ ### Community post (`/community/post`)
+
+ `post_id`* — a community post id (`post_id` from `/channel/community`) or a post URL.
+
+ ### Community post comments (`/community/post/comments`)
+
+ `post_id`* , `cursor` (a prior `next_cursor`, or `comments_cursor` from `/community/post`).
+
## Examples
```python
import requests
BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# 1. Search — use "search" field, not "query"
search = requests.post(f"{BASE}/api/v1/youtube/search", headers=HEADERS,
json={"search": "langchain tutorial", "type": "video", "sort_by": "view_count"}).json()
video_id = search["data"]["results"][0]["video_id"]
# 2. Full video metadata (captions list included)
video = requests.post(f"{BASE}/api/v1/youtube/video", headers=HEADERS,
json={"video_id": video_id}).json()
# 3. Transcript as plain text
transcript = requests.post(f"{BASE}/api/v1/youtube/transcript", headers=HEADERS,
json={"video_id": video_id, "language": "en", "format": "text"}).json()
# 4. Resolve a handle, then pull the channel's videos
resolved = requests.post(f"{BASE}/api/v1/youtube/channel/resolve", headers=HEADERS,
json={"channel": "@freecodecamp"}).json()
channel_id = resolved["data"]["channel_id"]
videos = requests.post(f"{BASE}/api/v1/youtube/channel/videos", headers=HEADERS,
json={"channel_id": channel_id}).json()
```
## Response shapes
Every response uses the envelope `{ data, response_time, credits_used, credits_remaining }`. Key `data` fields per endpoint:
- **search** — `results[]` (`type`, `video_id`, `title`, `url`, `description_snippet`, `thumbnail`, `duration_text`, `view_count`, `published_time`, `channel{id,name,url}`), plus `shorts`, `channels`, `playlists`, `next_cursor`, `has_more`.
- **shorts** — `results[]` (`video_id`, `title`, `url`, `thumbnail`, `view_count`, `published_time`, `author`, `channel_id`), `next_cursor`, `has_more`.
- **suggestions** — `suggestions[]` (strings), `total_count`.
- **video** — `video_id`, `title`, `author`, `channel_id`, `channel_url`, `published_at`, `description`, `length_seconds`, `view_count`, `keywords[]`, `thumbnail`, `playability_status`, `chapters`, `captions[]` (`language_code`, `language_name`, `url`).
- **comments** — `comments[]` (`comment_id`, `text`, `like_count`, `reply_count`, `published_time`, `reply_cursor`, `author{channel_id,name,url,avatar,is_verified,is_creator}`), `next_cursor`, `has_more`.
- **comments/replies** — `replies[]` (same item shape as a comment), `next_cursor`, `has_more`.
- **transcript** — `video_id`, `language_code`, `language_name`, `format`, `content`.
- **related** — `results[]` (`video_id`, `title`, `url`, `author`, `channel_id`, `channel_url`, `thumbnail`, `view_count`, `published_time`, `length_seconds`), `total_count`.
- **channel/search** — `results[]` (`channel_id`, `name`, `handle`, `url`, `thumbnail`, `subscriber_count`, `description`, `verified`), `next_cursor`, `has_more`, `total_count`.
- **channel** — `channel_id`, `title`, `description`, `handle`, `url`, `subscriber_count`, `video_count`, `view_count`, `country`, `creation_date`, `verified`, `has_business_email`, `avatar`, `banner`, `links[]`.
- **channel/videos** — `channel_id`, `results[]` (`video_id`, `title`, `url`, `thumbnail`, `duration_text`, `view_count`, `published_time`, `is_live`), `next_cursor`, `has_more`.
- **channel/shorts** — `channel_id`, `results[]` (`video_id`, `title`, `url`, `thumbnail`, `view_count`), `next_cursor`, `has_more`, `total_count`.
- **channel/community** — `channel_id`, `posts[]` (`post_id`, `url`, `text`, `author_name`, `author_channel_id`, `published_time`, `vote_count`, `comment_count`, `images[]`, `attachment_type`), `next_cursor`, `has_more`.
- **channel/resolve** — `channel_id`, `channel_url`.
+ - **community/post** — `post_id`, `url`, `text`, `author_name`, `author_channel_id`, `author_url`, `author_avatar`, `published_time`, `vote_count`, `comment_count` (can be null), `attachment_type`, `images[]`, `comments_cursor`.
+ - **community/post/comments** — `comments[]` (`comment_id`, `text`, `like_count`, `reply_count`, `published_time`, `reply_cursor`, `author{channel_id,name,url,avatar,is_verified,is_creator}`), `next_cursor`, `has_more`.
- **streams** — `video_id`, `title`, `author`, `length_seconds`, `view_count`, `is_live`, `formats[]`, `adaptive_formats[]`, `available_qualities[]`, `expires_in_seconds`.
```json
{
"data": {
"results": [
{
"type": "video",
"video_id": "sVcwVQRHIc8",
"title": "Learn RAG From Scratch - Python AI Tutorial",
"url": "https://www.youtube.com/watch?v=sVcwVQRHIc8",
"duration_text": "2:33:11",
"view_count": 1258310,
"published_time": "1 year ago",
"thumbnail": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg",
"channel": { "id": "UC8butISFwT-Wl7EV0hUK0BQ", "name": "freeCodeCamp.org", "url": "https://www.youtube.com/@freecodecamp" }
}
],
"next_cursor": "EpMD...",
"has_more": true
},
"credits_used": 2,
"credits_remaining": 998
}
```
## Guardrails
- The search parameter is `search`, not `query` — this is different from other Scavio endpoints.
- - Credits are not uniform: `search` and `shorts` cost 2, `streams` costs 3, `transcript` costs 8, and every other endpoint costs 1. Inform the user before paginating through many pages, especially transcripts.
+ - Credits are not uniform: `search` and `shorts` cost 2, `streams` costs 3, `transcript` costs 5, and every other endpoint costs 1. Inform the user before paginating through many pages, especially transcripts.
- `/metadata` is a deprecated alias of `/video`; use `/video` in new code.
- Stream URLs from `/streams` expire (`expires_in_seconds`) — use them promptly.
- Never fabricate video IDs, view counts, transcripts, comments, or channel data. Only return API data.
## Failure handling
- `400` means an invalid parameter (e.g. a missing `video_id` or `channel_id`) — fix and retry.
- `401` means the API key is invalid or missing. Check `SCAVIO_API_KEY`.
- `429` means rate or usage limit exceeded. Wait before retrying. See [rate limits](https://scavio.dev/docs/rate-limits?utm_source=agent-skills&utm_medium=skill&utm_campaign=youtube-data-api).
- `502` / `503` mean upstream is temporarily unavailable. Wait a few seconds before retrying.
- If search returns no results, suggest different keywords or relaxing filters.
- If a transcript is unavailable in the requested `language`, retry with `language: en` or check `/video` `captions[]` for available languages.
- If `SCAVIO_API_KEY` is not set, prompt the user to export it before continuing.
## LangChain
```bash
pip install langchain-scavio==4.0.2
```
```python
from langchain_scavio import ScavioSearchTool
tool = ScavioSearchTool(engine="youtube")
```