# YouTube Scraper

Scrape full channel data asynchronously and poll for results, or synchronously in one call.

### `POST /api/youtube-scraper`

Retrieve video data from a YouTube channel or single video. Returns public metadata (title, views, likes, duration, thumbnails) and optional comments. Transcript extraction is not available.

**Request Body (JSON)**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| url | string | Required | — | YouTube channel URL or video URL. Auto-detects single video vs. channel mode. |
| video_type | string | Optional | both | Type of videos to scrape: `shorts`, `videos`, or `both` |
| sort | string | Optional | recent | Sort order: `recent` or `popular` |
| max_videos | integer | Optional | 20 | Maximum videos to scrape (1–100) |
| include_comments | boolean | Optional | false | Include top comments for each video |

**Example Request**

```
# Retrieve a channel's most popular videos with comments
curl -X POST "https://api.algrow.online/api/youtube-scraper" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/@MrBeast",
    "video_type": "videos",
    "sort": "popular",
    "max_videos": 10,
    "include_comments": true
  }'
```

**Response 200 200**

```
{
  "success": true,
  "job_id": 4521,
  "mode": "channel",
  "message": "Scraping job queued. Poll /api/youtube-scraper/{job_id} for results."
}
```

200 Queued 400 Invalid URL 401 Auth failed 402 Subscription inactive

### `GET /api/youtube-scraper/:job_id`

Poll for the result of a YouTube scraping job. Returns `pending` or `processing` while running, and the full video data when `completed`.

**Example Request**

```
curl "https://api.algrow.online/api/youtube-scraper/4521" \
-H "Authorization: Bearer YOUR_API_KEY"
```

**Completed Response 200 200**

```
{
  "success": true,
  "job_id": 4521,
  "status": "completed",
  "created_at": "2026-03-24T10:30:00",
  "completed_at": "2026-03-24T10:31:15",
  "result": {
    "total_videos": 10,
    "total_views": 1250000000,
    "total_likes": 42000000,
    "videos": [
      {
        "video_id": "dQw4w9WgXcQ",
        "title": "Video Title Here",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
        "view_count": 250000000,
        "like_count": 8500000,
        "comment_count": 2100000,
        "duration_seconds": 212,
        "duration_human": "3m 32s",
        "publish_date": "2025-10-15T14:00:00Z",
        "channel": "MrBeast",
        "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "comments": [
          {
            "author": "@user123",
            "text": "Great video!",
            "likes": 5200,
            "published_time": "2 months ago"
          }
        ]
      }
    ]
  }
}
```

**Response Fields (per video)**

| Field | Type | Description |
| --- | --- | --- |
| video_id | string | YouTube video ID |
| title | string | Video title |
| url | string | Full YouTube URL |
| thumbnail | string | Thumbnail image URL (highest resolution available) |
| view_count | integer | Total views |
| like_count | integer | Total likes |
| comment_count | integer | Total comments |
| duration_seconds | integer | Video length in seconds |
| duration_human | string | Human-readable duration (e.g. “3m 32s”) |
| publish_date | string | Publish date (ISO 8601) |
| channel | string | Channel name |
| channel_id | string | YouTube channel ID |
| comments | array\|null | Top comments (only if `include_comments: true`) |

200 Success 401 Auth failed 404 Job not found

### `POST /api/youtube-scraper-fast`

Synchronous YouTube channel scrape — no job queue, no polling. Returns channel metadata + videos (and optional comments) inline in ~2–5s, the same shape as the queued `/api/youtube-scraper` result. Transcripts are NOT supported here (use the queued endpoint for those).

**Request Body (JSON)**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| url | string | Required | — | A YouTube channel URL (youtube.com or youtu.be). |
| video_type | string | Optional | both | shorts, videos, or both. |
| sort | string | Optional | recent | recent or popular. |
| max_videos | integer | Optional | 20 | 1–100. |
| include_comments | boolean | Optional | false | Include top comments per video. |
| max_comments | integer | Optional | 100 | 1–100, when include_comments is true. |

**Example Request**

```
curl -X POST "https://api.algrow.online/api/youtube-scraper-fast" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://youtube.com/@MrBeast", "video_type": "videos", "max_videos": 20}'
```

**Response 200 200**

```
{
  "success": true,
  "status": "completed",
  "result": { … channel + videos … }
}
```

200 Success 400 Validation error 401 Auth failed 503 Quota exhausted

### `POST /api/youtube-scraper/thumbnails`

Bulk thumbnail download. Returns one ZIP of JPEG thumbnails (`maxresdefault`, or `hqdefault` when a video has no max-res asset), numbered in the order given. Pass either a list of videos, or a channel URL to scrape and zip in one call. Up to 100 per call. No credit cost.

**Request Body (JSON)**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| video_ids | array \| string | Optional | — | Video IDs or video URLs, as a list or comma-separated string. Up to 100. |
| url | string | Optional | — | A YouTube channel URL, used when `video_ids` is not given. |
| video_type | string | Optional | both | With `url`: shorts, videos, or both. |
| sort | string | Optional | recent | With `url`: recent or popular. |
| max_videos | integer | Optional | 20 | With `url`: 1–100. |

**Example Request**

```
curl -X POST "https://api.algrow.online/api/youtube-scraper/thumbnails" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://youtube.com/@MrBeast", "sort": "popular", "max_videos": 50}' \
-o thumbnails.zip
```

**Response 200 200**

```
application/zip

001-Video-Title-VIDEOID.jpg
002-Another-Title-VIDEOID.jpg
...
```

200 Success 400 Validation error 401 Auth failed 502 No thumbnails returned