# 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 via the Data API v3 — 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