# YouTube Comments & Replies Scraper (`scraper-engine/youtube-comments-scraper`) Actor

YouTube Comments & Replies Scraper extracts comments from any public YouTube video or channel. Gather usernames, timestamps, likes, replies, and full comment text. Ideal for sentiment analysis, audience research, or content insights. Export clean structured data in JSON, CSV, or Excel.

- **URL**: https://apify.com/scraper-engine/youtube-comments-scraper.md
- **Developed by:** [Scraper Engine](https://apify.com/scraper-engine) (community)
- **Categories:** Videos, SEO tools, Agents
- **Stats:** 304 total users, 3 monthly users, 100.0% runs succeeded, 2 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

$19.99/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period. You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#rental-actors

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### YouTube Comments Scraper — Text, Likes, Replies and Author Data

Extract YouTube comments and their full reply threads as structured JSON — comment text, `voteCount` (likes), `author`, `authorChannelUrl`, `publishedAt`, and `replyCount` for every top-level comment and reply. Paste a video URL, an 11-character video ID, or a channel URL and the scraper does the rest, including expanding a channel into its latest videos. No YouTube account, no Google Cloud project, no YouTube Data API key required. Configure the input below and hit **Start** to get your first dataset in minutes.

### What is YouTube Comments Scraper with Replies?

YouTube Comments Scraper with Replies is an Apify Actor that reads a YouTube video's public comment section — top-level comments and their nested replies — and returns each one as a row of typed JSON with author, engagement, and timing data. It requires no YouTube account, no Google sign-in, and no API key; it reads the same public page and internal pagination endpoint your browser uses when you scroll through comments. It's built for marketers, social listening teams, researchers, and developers who need comment data in a database or LLM pipeline rather than read one by one in a browser.

### What YouTube comment data is publicly available to scrape?

Anyone who opens a YouTube video page — logged in or not — can read its comments, reply threads, like counts, and commenter display names without further permission from Google or the video owner.

| Data category | Publicly available (no login) | Restricted |
| --- | --- | --- |
| Comment text and reply text | ✅ | — |
| Like count (`voteCount`) and reply count (`replyCount`) | ✅ | — |
| Commenter display name and channel link | ✅ | — |
| Commenter avatar, verified badge, "hearted by creator" flag | ✅ | — |
| Relative publish time ("2 years ago") | ✅ | — |
| Exact publish timestamp | ⚠️ approximated | Only YouTube's own systems and the official API return a precise value |
| Comments on a video with comments turned off or a private/unlisted video the link owner hasn't shared | — | ❌ not exposed on the public page |
| Commenter's email address or account details beyond their public channel | — | ❌ never shown publicly |

YouTube Comments Scraper with Replies only returns publicly visible data — what any visitor sees on the video page. Nothing behind a login wall.

### What data can I extract with YouTube Comments Scraper with Replies?

The scraper returns one row per comment and one row per reply, both using the same 27-field schema (the dataset's default view lists all 27 — there is no hidden subset).

#### Comment & author identity

| Field | Description |
| --- | --- |
| `cid` | Unique YouTube comment ID |
| `type` | `"comment"` for top-level comments, `"reply"` for replies |
| `isReply` | Boolean — `true` if this row is a reply |
| `comment` | The comment or reply text |
| `author` | Commenter's display name, normalized to start with `@` |
| `authorChannelId` | Commenter's YouTube channel ID |
| `authorChannelUrl` | Full URL to the commenter's channel, built from `authorChannelId` |
| `avatar` | URL of the commenter's avatar image |
| `videoId` | The 11-character ID of the video the comment belongs to |
| `pageUrl` | The video's watch URL |
| `title` | The video's title |
| `commentUrl` | Deep link to the specific comment (video URL + `&lc=<cid>`) |
| `replyToCid` | The parent comment's `cid`, present only on replies |

#### Engagement, verification and timing

| Field | Description |
| --- | --- |
| `voteCount` | Number of likes on the comment |
| `replyCount` | Number of replies YouTube reports for a top-level comment |
| `commentsCount` | Total comment count YouTube reports for the video, repeated on every row |
| `authorIsChannelOwner` | Boolean — true if the commenter owns the video's channel |
| `isVerified` | Boolean — true if the commenter's channel carries YouTube's verified badge |
| `hasCreatorHeart` | Boolean — true if the video's creator "hearted" this comment |
| `publishedTimeText` | YouTube's own relative time string, e.g. `"2 years ago"` |
| `publishedAt` | ISO-8601 UTC timestamp **approximated** from `publishedTimeText` (see the FAQ below) |
| `scrapedAt` | ISO-8601 UTC timestamp of when the scraper collected the row |

#### 🤖 AI enrichment fields (only present when `aiEnhancement` is on)

| Field | Description |
| --- | --- |
| `sentiment` | `"positive"`, `"negative"`, or `"neutral"` |
| `emotion` | One of `joy`, `anger`, `sadness`, `fear`, `surprise`, `disgust`, `neutral` |
| `language` | ISO 639-1 language code detected in the comment |
| `topics` | Up to 3 short topic tags |
| `toxicityScore` | A 0.0 (clean) to 1.0 (toxic) score |

#### 🤖 Add-on: Need additional YouTube data?

If you also need channel-level metrics — subscriber counts, upload cadence, creator analytics — pair this Actor with [YouTube Channel Finder With Creator Analytics](https://apify.com/scraper-engine/youtube-channel-finder-with-creator-analytics) (`youtube-channel-finder-with-creator-analytics`) from the same account. Run it first to shortlist channels, then feed the resulting video or channel URLs straight into this Actor's `startUrls`.

### How does YouTube Comments Scraper with Replies differ from the official YouTube Data API?

The official [YouTube Data API v3](https://developers.google.com/youtube/v3) can return comments through its `commentThreads.list` endpoint, but it requires a Google Cloud project, an API key, and counts every call against a shared daily quota — Google's own getting-started documentation states new projects get "a default quota allocation of... 10,000 units per day combined for all other endpoints" (as observed on Google's YouTube Data API documentation, checked 2026-07-26). YouTube Comments Scraper with Replies reads the same public comment data without any of that setup.

| Feature | YouTube Data API v3 | YouTube Comments Scraper with Replies |
| --- | --- | --- |
| Setup | Google Cloud project + API key (OAuth for some calls) | Apify account only |
| Daily cap | Shared 10,000-unit default quota across all endpoints | No published unit cap — bounded only by your own `maxComments` / `maxRepliesPerComment` |
| Reply threads | Separate `comments.list` call per parent comment ID | Replies fetched automatically and interleaved under each parent |
| Channel-wide runs | You enumerate videos yourself via `search.list` or `playlistItems.list` | Paste a channel URL — `maxVideosPerChannel` expands it internally |
| Sentiment / topic tagging | Not offered — raw text only | Optional AI enrichment (`aiEnhancement`) across 7 providers |
| Keyword / date / like filtering | Not built in — filter client-side after fetching | `keywords`, `excludeKeywords`, `minLikes`, `oldestCommentDate` filter before rows are pushed |

Use the official API if you're building a Google-verified app that needs OAuth-scoped write access (posting or moderating comments). Use YouTube Comments Scraper with Replies for read-only bulk comment extraction without Google credentials or quota management.

### How to use YouTube Comments Scraper with Replies

The Actor runs on the Apify platform — no local install, no scraping infrastructure to maintain.

1. Open YouTube Comments Scraper with Replies on its Apify Store page.
2. Provide the required input: at least one entry in `startUrls` — a video URL, an 11-character video ID, or a channel URL.
3. Optionally set `maxComments`, `sortOrder`, `includeReplies`, and the `keywords` / `excludeKeywords` / `minLikes` / `oldestCommentDate` filters.
4. Click **Start**.
5. Open the **Dataset** tab when the run finishes and export as JSON, CSV, Excel, or XML — or pull results via the Apify API.

#### How to scale to bulk comment extraction

`startUrls` is an array, so a single run can process any number of video URLs, video IDs, and channel URLs together — the Actor loops through them one by one. To pull comments from an entire channel, add the channel URL (`https://www.youtube.com/@handle`, `/channel/UC...`, `/c/name`, or `/user/name`) and set `maxVideosPerChannel` to control how many of its latest videos get scraped.

### What can you do with YouTube comment data?

- 📊 **Social listening teams** monitoring a launch use `sentiment` and `topics` (with `aiEnhancement` on) alongside `publishedAt` to track how audience reaction shifts over the days after a video goes live.
- 🎯 **Marketers** benchmarking a campaign use `voteCount` and `replyCount` to rank which comments resonated most and pull direct quotes with `comment` and `commentUrl`.
- 🔬 **Researchers** studying discourse use `keywords` and `excludeKeywords` at scrape time to isolate comment threads about a specific topic without downloading everything first.
- 🏢 **Brand and reputation teams** use `toxicityScore` and `emotion` to flag comment threads that need a moderation or support response.
- 🤖 **AI engineers** feed `comment`, `author`, and `title` into a RAG index or an LLM-based summarization agent to generate audience-sentiment reports without writing a YouTube parser.

### How does YouTube Comments Scraper with Replies handle rate limits and blocking?

By default the Actor makes requests with no proxy at all. If YouTube responds with a 403 or 429, or a proxy connection fails, it automatically escalates: no proxy → Apify Proxy datacenter tier → Apify Proxy residential tier, retrying up to 3 times per request with a growing delay between attempts (roughly 2, 4, and 6 seconds). You can also pass your own `proxyConfiguration` to start on a specific proxy tier or group. If a video's page can't be fetched at all after retries, the Actor logs an error and moves on to the next URL in `startUrls` rather than failing the whole run.

### ⬇️ Input

| Parameter | Required | Type | Description | Example value |
| --- | --- | --- | --- | --- |
| `startUrls` | Yes | array | Video URLs, 11-character video IDs, or channel URLs (`@handle`, `/channel/UC...`, `/c/name`, `/user/name`). Channel URLs expand to their latest videos. | `["https://www.youtube.com/watch?v=KrLj6nc516A"]` |
| `maxComments` | No | integer (default `10`, min `0`) | Max top-level comments per video. Replies are additional, controlled by `maxRepliesPerComment`. `0` = no limit. | `25` |
| `sortOrder` | No | string (default `"top"`, enum `top` / `newest`) | `top` = most liked first, `newest` = most recent first. Auto-switches to `newest` when `oldestCommentDate` is set. | `"newest"` |
| `includeReplies` | No | boolean (default `true`) | Collect reply (child) comments. Turn off to scrape only top-level comments. | `true` |
| `maxRepliesPerComment` | No | integer (default `0`, min `0`) | Cap replies collected per top-level comment. `0` = no limit. | `5` |
| `keywords` | No | array | Keep only comments containing at least one of these words/phrases (case-insensitive). Empty = keep all. | `["pricing", "shipping"]` |
| `excludeKeywords` | No | array | Drop comments containing any of these words/phrases (case-insensitive). | `["spam"]` |
| `minLikes` | No | integer (default `0`, min `0`) | Keep only comments with at least this many likes (`voteCount`). | `5` |
| `oldestCommentDate` | No | string | Keep only comments newer than this. Accepts an absolute date (`2026-01-15`) or a relative period (`7 days`, `3 months`, `1 year`). Auto-switches sort to `newest`. | `"3 months"` |
| `maxVideosPerChannel` | No | integer (default `10`, min `1`) | When a channel URL is provided, scrape comments from up to this many of its latest videos. | `5` |
| `aiEnhancement` | No | boolean (default `false`) | Add `sentiment`, `emotion`, `language`, `topics`, and `toxicityScore` to each comment via the AI provider you choose below. Requires an API key. | `true` |
| `aiModel` | No | string (default `"claude-haiku-4-5"`), enum of 31 models across 7 providers | Pick the model; provider is auto-detected from the name prefix (`claude-*` = Anthropic, `gpt-*`/`o1`/`o3-*` = OpenAI, `gemini-*` = Google, `grok-*` = xAI, `deepseek-*` = DeepSeek, `sonar*` = Perplexity, `mistral-*` = Mistral). | `"claude-haiku-4-5"` |
| `aiApiKey` | No | string (secret) | API key for the selected provider. Falls back to an environment variable: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `XAI_API_KEY`/`GROK_API_KEY`, `DEEPSEEK_API_KEY`, `PERPLEXITY_API_KEY`/`PPLX_API_KEY`, or `MISTRAL_API_KEY`. | `"sk-ant-..."` |
| `proxyConfiguration` | No | object (proxy editor) | Proxy settings. Default: no proxy, with automatic fallback to datacenter then residential if blocked. | `{"useApifyProxy": false}` |

#### Example input

```json
{
  "startUrls": [
    "https://www.youtube.com/watch?v=KrLj6nc516A",
    "https://www.youtube.com/@MrBeast"
  ],
  "maxComments": 25,
  "sortOrder": "top",
  "includeReplies": true,
  "maxRepliesPerComment": 5,
  "keywords": ["giveaway"],
  "excludeKeywords": ["spam"],
  "minLikes": 5,
  "oldestCommentDate": "3 months",
  "maxVideosPerChannel": 5,
  "aiEnhancement": true,
  "aiModel": "claude-haiku-4-5",
  "aiApiKey": "",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

### ⬆️ Output

Every comment and reply is pushed as one typed, normalized JSON row with a consistent 27-field schema — including the AI fields, which are present (and populated) only when `aiEnhancement` is on. Replies are additionally mirrored into a dedicated per-run dataset named `replies-<runId>`, using the exact same schema, so you can pull only replies without filtering `type`. Export from the **Dataset** tab as JSON, CSV, Excel, or XML, or stream results through the Apify API.

#### Example output

```json
{
  "cid": "UgzxS4_5UJwAI1xrNF14AaABAg",
  "type": "comment",
  "isReply": false,
  "publishedTimeText": "1 year ago",
  "publishedAt": "2025-07-26T09:12:00Z",
  "comment": "This challenge was insane, respect for actually finishing it!",
  "author": "@_Kevin_1",
  "authorChannelId": "UCyc0emnCfdnTEGr0A5sK2yA",
  "authorChannelUrl": "https://www.youtube.com/channel/UCyc0emnCfdnTEGr0A5sK2yA",
  "avatar": "https://yt3.ggpht.com/abc123=s176-c-k-c0x00ffffff-no-rj",
  "authorIsChannelOwner": false,
  "isVerified": false,
  "voteCount": 2043,
  "hasCreatorHeart": true,
  "replyCount": 1,
  "replyToCid": null,
  "commentUrl": "https://www.youtube.com/watch?v=KrLj6nc516A&lc=UgzxS4_5UJwAI1xrNF14AaABAg",
  "videoId": "KrLj6nc516A",
  "pageUrl": "https://www.youtube.com/watch?v=KrLj6nc516A",
  "title": "$1 vs $100,000,000 Car!",
  "commentsCount": 158342,
  "scrapedAt": "2026-07-26T10:00:00Z",
  "sentiment": "positive",
  "emotion": "joy",
  "language": "en",
  "topics": ["challenge", "cars"],
  "toxicityScore": 0.01
}
```

### How does it work?

YouTube Comments Scraper with Replies makes plain HTTP requests to the same public video page and the same internal `/youtubei/v1/next` pagination endpoint your browser calls when you scroll through comments — there's no headless browser involved. It reads the `ytInitialData` JSON embedded in the video page to get a continuation token, client version, and visitor ID, then uses those to request further pages of comments and, separately, reply threads under each parent comment. Requests go out with no proxy by default and automatically escalate through Apify Proxy's datacenter and residential tiers if YouTube responds with a block. Only publicly visible comment data is ever returned, and the 27-field output schema stays the same regardless of changes to YouTube's page layout, since the Actor parses the underlying data structure rather than rendered HTML text.

### Integrations

YouTube Comments Scraper with Replies runs on Apify, so it works with anything that can call the Apify API or trigger an Apify Actor run.

#### Calling YouTube Comments Scraper with Replies programmatically

```python
from apify_client import ApifyClient

client = ApifyClient("<APIFY_API_TOKEN>")

run_input = {
    "startUrls": ["https://www.youtube.com/watch?v=KrLj6nc516A"],
    "maxComments": 25,
    "includeReplies": True,
}

run = client.actor("youtube-comments-scraper-with-replies").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["author"], item["comment"])
```

Works in Go, Ruby, Node.js, cURL — any language that can make an HTTP request against the Apify API.

#### No-code tools (n8n, Make, LangChain)

In **n8n**, use the Apify node (or a generic HTTP Request node against `https://api.apify.com/v2/acts/youtube-comments-scraper-with-replies/runs`) to start a run, then poll or use a webhook to fetch the dataset once it finishes. In **Make**, the Apify app module offers the same "Run an Actor" and "Get dataset items" actions, so a scenario can trigger a run on a schedule and feed rows into a Google Sheet or CRM. In **LangChain**, wrap the Apify Python client's `call()` and `iterate_items()` calls in a custom tool so an agent can pull fresh comment data as part of a larger chain.

### Is it legal to scrape YouTube comments?

Scraping publicly available YouTube comments is generally legal, since this Actor collects only data any visitor can already see without logging in. Comment author names, avatars, and channel links can constitute personal data about the commenters, so if you store or process this data at scale you should have a lawful basis under GDPR (EU/UK users) or comply with the CCPA (California users) — for example, a documented legitimate interest for sentiment or brand-monitoring research, with a defined retention period. You are also responsible for complying with YouTube's own Terms of Service for your use case. Consult legal counsel if your use case involves bulk storage of personal data.

### Frequently asked questions

#### What YouTube comment fields does YouTube Comments Scraper with Replies return?

The top fields are `comment` (the text), `author`, `voteCount` (likes), `publishedAt`, and `replyCount`. See the [data fields section](#what-data-can-i-extract-with-youtube-comments-scraper-with-replies) above for the complete 27-field schema.

#### Does YouTube Comments Scraper with Replies require a YouTube account or login?

No. The source code makes unauthenticated HTTP requests to YouTube's public video page and its public comment-pagination endpoint — no Google sign-in, cookies, or session are used.

#### How many comments can I extract in one run?

There's no fixed cap in the Actor itself — `maxComments` (default `10`) controls top-level comments per video, and `0` removes the limit entirely; `maxRepliesPerComment` (default `0`, meaning unlimited) controls replies per comment separately.

#### What happens if a video has comments disabled or the page can't be loaded?

The Actor logs an error for that specific video (`❌ Failed to extract data from video page`) and moves on to the next URL in `startUrls` — one bad video does not stop the rest of the run. If a URL can't be parsed into a valid video ID at all, it's skipped with a warning before any request is made.

#### Can I scrape multiple YouTube videos or channels at once?

Yes. `startUrls` is an array — mix video URLs, video IDs, and channel URLs in the same run, and the Actor processes them sequentially, expanding any channel URL into its latest videos first.

#### Does YouTube Comments Scraper with Replies work with Claude, ChatGPT, and other AI agent tools?

It's callable as an HTTP endpoint through the Apify API by any agent framework that can make requests. Separately, its own `aiEnhancement` option can call Claude, ChatGPT, Gemini, Grok, DeepSeek, Perplexity, or Mistral directly to classify each comment's sentiment, emotion, language, topics, and toxicity as part of the run.

#### How does YouTube Comments Scraper with Replies compare to other YouTube comment scrapers?

As observed on the Apify Store on 2026-07-26, memo23's `youtube-comments-scraper` documents comment and reply data but not channel-wide input, keyword/date/like filtering, or AI enrichment. delicious\_zebu's `youtube-comments-replies-scraper` documents first- and second-level comments but not channel URLs, absolute timestamps, or filters. parseforge's `youtube-comments-scraper` documents optional AI sentiment analysis and up to 1,000,000 comments on a paid plan, but its listed 17 fields don't include vote/reply counts, verified badges, or "hearted by creator" flags. YouTube Comments Scraper with Replies combines channel-wide scraping, a dedicated replies dataset, `keywords`/`excludeKeywords`/`minLikes`/`oldestCommentDate` filtering, and 7-provider AI enrichment in one Actor — a combination none of the three competitor listings document together as of the date checked.

#### Does YouTube Comments Scraper with Replies return data in a format LLMs can use directly?

Yes. Every row is typed, normalized JSON with consistent field names across runs — no HTML parsing or CSS selectors required. Pass rows directly to an LLM, index `comment` text into a vector store, or feed the dataset to an agent tool.

#### What happens when YouTube changes its comment layout or anti-bot system?

The Actor parses YouTube's underlying data structures (`ytInitialData` and the `/youtubei/v1/next` JSON response) rather than rendered HTML, and the 27-field output schema is designed to stay stable across UI changes. No specific update turnaround time is published.

#### Can I use YouTube Comments Scraper with Replies without managing proxies or browser infrastructure?

Yes. By default it runs with no proxy and automatically escalates to Apify Proxy's datacenter, then residential, tier if YouTube blocks a request — you don't need to configure or rotate anything yourself unless you want to override the default with your own `proxyConfiguration`.

#### Why is `publishedAt` an approximation instead of an exact timestamp?

Because YouTube's public comment page only exposes a relative string like `"2 years ago"` (captured as-is in `publishedTimeText`), not an exact date. The Actor converts that string to an ISO-8601 UTC value in `publishedAt` by subtracting the stated period from the scrape time — treat `publishedAt` as an estimate accurate to the unit YouTube displayed (day, month, or year), not a precise second-level timestamp.

#### Which comment fields work best for AI training data and RAG indexing?

For RAG, index `comment` alongside `title` and `author` for context. For structured training data, `voteCount`, `replyCount`, `isReply`, and `authorIsChannelOwner` are the most consistently populated numeric and boolean fields across every run, and all fields return as typed primitives (strings, integers, booleans) rather than nested objects.

### 🔗 Related scrapers

| Scraper | What it extracts |
| --- | --- |
| [YouTube Channel Finder With Creator Analytics](https://apify.com/scraper-engine/youtube-channel-finder-with-creator-analytics) | Channel-level metrics and creator analytics for YouTube channels |
| [Facebook Comments & Replies Scraper with AI Enrichment](https://apify.com/scraper-engine/facebook-comments-scraper-with-replies-ai) | Comments and reply threads from Facebook posts, with the same style of AI enrichment |
| [Instagram Tagged Posts Scraper — Comments, Media & Metadata](https://apify.com/scraper-engine/instagram-tagged-posts-scraper-plus) | Comments, media, and metadata from Instagram tagged posts |
| [Instagram Followers And Following Scraper with AI Enrichment](https://apify.com/scraper-engine/instagram-followers-following-scraper) | Follower and following lists with optional AI enrichment |

### 💬 Your feedback

Found a bug or missing a field? Let us know through the Actor's **Issues** tab on Apify Console, or leave a review on the Store listing — both are monitored and help prioritize fixes and new fields.

# Actor input Schema

## `startUrls` (type: `array`):

📋 Enter YouTube video URLs, 11-char video IDs, OR channel URLs (https://www.youtube.com/@handle, /channel/UC..., /c/name, /user/name). Channel URLs are expanded to their latest videos (see Max Videos per Channel).

## `maxComments` (type: `integer`):

🔢 Max TOP-LEVEL comments to scrape per video (replies are additional, controlled by Max Replies per Comment). Example: maxComments=10 + maxReplies=3 → up to 10 comments and up to 30 replies. Use 0 for no limit. Default is 10.

## `sortOrder` (type: `string`):

⬆️ 'top' = most liked first; 'newest' = most recent first. (Auto-switches to 'newest' when Oldest Comment Date is set.)

## `includeReplies` (type: `boolean`):

Include reply comments (child comments). Turn off to only scrape top-level comments.

## `maxRepliesPerComment` (type: `integer`):

Cap the number of replies collected per top-level comment. Use 0 for no limit.

## `keywords` (type: `array`):

Only keep comments whose text contains at least one of these words/phrases (case-insensitive). Leave empty to keep all.

## `excludeKeywords` (type: `array`):

Drop comments whose text contains any of these words/phrases (case-insensitive).

## `minLikes` (type: `integer`):

Only keep comments with at least this many likes (voteCount).

## `oldestCommentDate` (type: `string`):

Only keep comments newer than this. The date picker has a toggle to switch between an ABSOLUTE calendar date (e.g. 2026-01-15) and a RELATIVE period (e.g. '7 days', '3 months', '1 year'). Both are supported. Auto-switches sort to 'newest'.

## `maxVideosPerChannel` (type: `integer`):

When a channel URL is provided, scrape comments from up to this many of its latest videos.

## `aiEnhancement` (type: `boolean`):

Add sentiment, emotion, detected language, topic tags, and a toxicity score to each comment using the AI provider you choose below. Requires an API key for that provider.

## `aiModel` (type: `string`):

Pick the model. The provider is auto-detected from the name: claude-\* = Anthropic, gpt-*/o1/o3 = OpenAI (ChatGPT), gemini-* = Google, grok-\* = xAI, deepseek-\* = DeepSeek, sonar\* = Perplexity, mistral-\* = Mistral. Cheaper 'mini'/'flash'/'haiku'/'lite' models are recommended for classification.

## `aiApiKey` (type: `string`):

API key for the selected provider. Falls back to an env var: ANTHROPIC\_API\_KEY (Claude), OPENAI\_API\_KEY (ChatGPT), GEMINI\_API\_KEY/GOOGLE\_API\_KEY (Gemini), XAI\_API\_KEY/GROK\_API\_KEY (Grok), DEEPSEEK\_API\_KEY (DeepSeek), PERPLEXITY\_API\_KEY/PPLX\_API\_KEY (Perplexity), or MISTRAL\_API\_KEY (Mistral).

## `proxyConfiguration` (type: `object`):

🛡️ Proxy settings. Default: no proxy, with automatic fallback to datacenter then residential if blocked.

## Actor input object example

```json
{
  "startUrls": [
    "https://www.youtube.com/watch?v=KrLj6nc516A"
  ],
  "maxComments": 10,
  "sortOrder": "top",
  "includeReplies": true,
  "maxRepliesPerComment": 0,
  "minLikes": 0,
  "maxVideosPerChannel": 10,
  "aiEnhancement": false,
  "aiModel": "claude-haiku-4-5",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Top-level comments and replies (reply rows have isReply=true / type="reply") from the Actor's default dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        "https://www.youtube.com/watch?v=KrLj6nc516A"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scraper-engine/youtube-comments-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrls": ["https://www.youtube.com/watch?v=KrLj6nc516A"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scraper-engine/youtube-comments-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    "https://www.youtube.com/watch?v=KrLj6nc516A"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scraper-engine/youtube-comments-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scraper-engine/youtube-comments-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/X1hcO2DDL89v1ScMC/builds/ycqqbChmxAh8KFbXh/openapi.json