SurfSense DocsYouTube
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
POST /api/v1/workspaces/{workspace_id}/scrapers/youtube/scrapeGive 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 |
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
POST /api/v1/workspaces/{workspace_id}/scrapers/youtube/commentsGive 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.