mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-07-08 22:22:17 +02:00
54 lines
2.2 KiB
Text
54 lines
2.2 KiB
Text
---
|
||
title: YouTube
|
||
description: Scrape public YouTube videos, channels, playlists, and comments
|
||
---
|
||
|
||
The YouTube scraper has two verbs: **scrape** for video metadata (and optionally subtitles) and **comments** for a video's comment threads.
|
||
|
||
## Scrape videos
|
||
|
||
```bash
|
||
POST /api/v1/workspaces/{workspace_id}/scrapers/youtube/scrape
|
||
```
|
||
|
||
Give it YouTube URLs (video, channel `/@handle`, playlist, shorts, or hashtag pages) and/or search queries. Returns structured video items — title, views, likes, publish date, channel info, description, and optionally subtitles.
|
||
|
||
At least one of `urls` or `search_queries` is required.
|
||
|
||
| Field | Default | Description |
|
||
|-------|---------|-------------|
|
||
| `urls` | — | Video, channel, playlist, shorts, or hashtag URLs (max 20 sources per call, combined with queries) |
|
||
| `search_queries` | — | Search terms; each returns up to `max_results` videos |
|
||
| `max_results` | `10` | Max items per source and per content type (a channel's videos, shorts, and streams are capped independently; max 1000) |
|
||
| `download_subtitles` | `false` | Also fetch each video's subtitle track (slower) |
|
||
| `subtitles_language` | `en` | Subtitle language code |
|
||
|
||
```bash
|
||
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/youtube/scrape" \
|
||
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"urls": ["https://www.youtube.com/@surfsense"],
|
||
"max_results": 20
|
||
}'
|
||
```
|
||
|
||
Billing is per returned video/short/stream.
|
||
|
||
## Fetch comments
|
||
|
||
```bash
|
||
POST /api/v1/workspaces/{workspace_id}/scrapers/youtube/comments
|
||
```
|
||
|
||
Give it video URLs; returns comment items with author, text, like count, reply relationships, and timestamps — useful for gauging sentiment on specific videos.
|
||
|
||
| Field | Default | Description |
|
||
|-------|---------|-------------|
|
||
| `urls` | required | 1–20 video URLs |
|
||
| `max_comments` | `20` | Max items per video, counting top-level comments and replies (max 100,000) |
|
||
| `sort_by` | `NEWEST_FIRST` | `TOP_COMMENTS` or `NEWEST_FIRST` |
|
||
|
||
Billing is per returned comment or reply.
|
||
|
||
For the full input and output JSON schemas and generated code snippets in your language, open **API Playground → YouTube** in your workspace.
|