# YouTube Comments Scraper (`apihq/youtube-comments-scraper`) Actor Export YouTube comments and replies to JSON by video URL or ID. Comments-off or deleted videos return success:false, cost $0, and never break the batch. One record per comment with author, likes, replies, and timestamp. $0.40 per 1,000 comments. - **URL**: https://apify.com/apihq/youtube-comments-scraper.md - **Developed by:** [apihq](https://apify.com/apihq) (community) - **Categories:** Social media, Videos, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $0.40 / 1,000 comments This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Export a public YouTube video's comments and replies as clean JSON from a video URL or ID. No YouTube Data API key, no quota, no browser. The contract is simple: **a video with comments off never fails your run, and you only pay for comments delivered.** Paste a deleted video, a bad ID, or a video with comments turned off, and it comes back as a `success: false` row while the rest of the batch keeps going. Pay-per-result at $0.40 per 1,000 comments. Failed videos cost $0. ### See one run Input: ```json { "videoUrls": ["dQw4w9WgXcQ", "00000000000"], "maxComments": 5 } ```` What comes back: - 5 `success: true` comment rows from the good video, billed - 1 `success: false` row, `code: VIDEO_NOT_FOUND`, for the bad ID, not billed - Run status: **SUCCEEDED** - Charged: 5 comments = $0.002 That is the whole contract. Good input returns billed rows, bad input returns free error rows in the same dataset, and the run still succeeds so one bad video never costs you a batch. ### Why this Actor - **A bad video never breaks the batch.** A deleted or private video, or one with comments disabled, returns a `success: false` record with a machine-readable `code` (`VIDEO_NOT_FOUND`, `COMMENTS_DISABLED`, `VALIDATION_FAILED`, `VIDEO_COMMENTS_TIMEOUT`, `DEADLINE_EXCEEDED`). Branch on `code` without parsing English. - **You pay only for comments.** Billing fires on an explicit per-comment event, not on dataset writes, so failure rows sit in your dataset for free. There is no per-run start fee, so a run that returns zero comments costs zero. - **No YouTube Data API key, no quota.** The official YouTube Data API needs a Google key and rations a daily quota per call. This reads public data directly, so there is no Google key to provision and no daily Data API quota to ration. (You still run it with your normal Apify account, like any Actor.) ### Best for Data and AI workflows that turn video discussion into text: sentiment and brand-safety analysis, audience research, moderation and spam review, and building comment datasets for LLM pipelines. The failure-free billing and machine-readable error rows matter most when the extraction runs unattended inside a larger pipeline, where one comments-off video should never take down the batch. It works fine for one-off manual pulls too. ### Input example A single video, top comments: ```json { "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "maxComments": 100, "sort": "top" } ``` A batch, newest first, with replies: ```json { "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "kJQP7kiw5Fk", "https://youtu.be/9bZkp7q19f0" ], "maxComments": 200, "sort": "newest", "includeReplies": true } ``` `videoUrl` and `videoUrls` are merged and de-duplicated. Up to 50 unique videos run per job. Each video is walked until `maxComments` (which counts top-level comments and replies together). ### Output example One record per comment. The video's id is copied onto every row so each row stands alone: ```json { "success": true, "video_id": "dQw4w9WgXcQ", "video_title": "Rick Astley - Never Gonna Give You Up (Official Video)", "comment_id": "Ugzge340dBgB75hWBm54AaABAg", "text": "can confirm: he never gave us up", "like_count": "264K", "reply_count": 961, "published_time": "1 year ago", "reply_level": 0, "is_pinned": true, "is_hearted": true, "author_name": "@YouTube", "author_channel_id": "UCBR8-60-B28hp2BmDPdntcQ", "author_is_verified": true, "author_is_creator": false, "author_is_artist": false, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ&lc=Ugzge340dBgB75hWBm54AaABAg" } ``` A video that cannot be found lands in the same dataset and is not charged: ```json { "success": false, "video_url": "00000000000", "code": "VIDEO_NOT_FOUND", "error": "Video not found or unavailable: 00000000000", "request_id": "req_911f37d2e55644ff9d9e4a3f", "status_code": 404 } ``` Split hits from misses on the `success` field. Quote `request_id` in any support issue and we can trace the exact request. ### What you get Every comment is one record with `success: true`: | Field | Type | What it is | |---|---|---| | `success` | boolean | `true` for a comment (billed), `false` for a video that could not be listed (not billed). | | `video_id` | string | The 11-character video ID the comment belongs to. | | `video_title` | string | The video's title. | | `comment_id` | string | The comment's unique ID. | | `text` | string | The comment body. | | `like_count` | string | Likes as a display string (for example `264K`). May be empty. | | `reply_count` | integer | Number of replies on the comment. | | `published_time` | string | Relative publish string (for example `1 year ago`). | | `reply_level` | integer | `0` for a top-level comment, `1`+ for a reply. | | `parent_comment_id` | string | On reply rows: the top-level comment they belong to. | | `is_pinned` | boolean | True if the comment is pinned. | | `is_hearted` | boolean | True if the creator hearted the comment. | | `author_name` | string | Author display name (for example `@handle`). | | `author_channel_id` | string | The author's `UC...` channel ID. | | `author_thumbnail_url` | string | The author's avatar URL. | | `author_is_verified` | boolean | True if the author's channel is verified. | | `author_is_creator` | boolean | True if the author is the video's channel owner. | | `author_is_artist` | boolean | True if the author is an official artist channel. | | `url` | string | Direct link to the comment. | Videos that could not be listed carry `success: false`, `video_url`, a machine-readable `code`, a human-readable `error`, the service `request_id`, and the HTTP `status_code`. They are not charged. ### Pricing Pay-per-result. One charge per comment delivered: `$0.0004` each, which is `$0.40 per 1,000 comments`. Replies (when `includeReplies` is on) bill at the same per-comment rate. The charge fires only after a comment row lands in your dataset. - 1,000 delivered comments cost $0.40. - A run that hits only comments-off or deleted videos costs $0. - There is no per-run start fee, so an empty run is genuinely free. Apify subscriber discounts apply automatically: roughly `$0.32 per 1,000` on the Scale plan and `$0.24 per 1,000` on Business. Platform compute is included in the per-comment price. Cap the maximum spend of a single run from Apify's Run Limits panel; the Actor honors the cap and stops cleanly mid-thread when the budget runs out. ### What this Actor does not do Honest scope, so you know before you run it: - **Replies are opt-in.** By default it returns top-level comments only. Set `includeReplies: true` to also fetch replies; they count toward `maxComments` and add extra requests. - **Comments-off videos return no comments.** A video with comments disabled comes back as a `success: false` row with `code: COMMENTS_DISABLED`, not an error that stops the run. - **Public videos only.** Private, deleted, and members-only videos return `success:false`. - **It reads video comments.** Community-post comments and live-chat messages are out of scope. ### How to use this Actor 1. Open the Actor in the Apify Console. 2. Set `videoUrl` (single), `videoUrls` (a list), or both. Each accepts a watch URL, a Shorts URL, a `youtu.be` link, or a bare 11-character video ID. Up to 50 unique videos run per job. 3. Set `maxComments` to cap how many comment rows to return per video, `sort` to `top` or `newest`, and `includeReplies` if you want replies. 4. Click Start. Each comment is one `success: true` record. Videos that cannot be listed produce one `success: false` record and do not stop the run. Only comments are charged. The Actor is also callable from the Apify API and every official integration (Make, Zapier, n8n, Slack, webhooks). The API tab in the Console has ready-to-paste JavaScript, Python, and curl snippets. ### Reliability **A bad video never fails the batch.** A deleted video, a mistyped ID, or a comments-off video becomes a `success: false` record with a specific `code`. The run keeps going and finishes successfully. **You never pay for a failure.** Billing fires on an explicit per-comment charge event, not on dataset writes, so `success: false` records are free. There is no per-run start fee either. **Hard 30-second deadline per page request.** Each page of comments is fetched under a 30-second deadline. If YouTube or the proxy network stalls, that video returns a `504` with `code: DEADLINE_EXCEEDED` as a `success: false` record instead of hanging your run. ### FAQ **Do I need a YouTube Data API key?** No. The Actor reads YouTube's public data directly and does not consume Google API quota. **What video formats are accepted?** A watch URL (`https://www.youtube.com/watch?v=...`), a Shorts URL, a `youtu.be` link, or a bare 11-character video ID. Unrecognizable input comes back as a `success: false` record with `code: VALIDATION_FAILED`, not a rejected run. **How do I get replies?** Set `includeReplies: true`. Reply rows carry `reply_level: 1` and `parent_comment_id` so you can reconstruct threads. Replies count toward `maxComments`. **What if a video has comments turned off?** It comes back as a `success: false` record with `code: COMMENTS_DISABLED`. You are not charged. **Can I sort comments?** Yes. Set `sort` to `top` (most relevant, the default) or `newest` (most recent first). **Can I also get the video's transcript or a channel's videos?** Yes, with the sibling Actors: [YouTube Transcript Scraper](https://apify.com/apihq/youtube-transcript-scraper) for captions, [YouTube Channel Scraper](https://apify.com/apihq/youtube-channel-scraper) for a channel's videos, and [YouTube Shorts Scraper](https://apify.com/apihq/youtube-shorts-scraper) for Shorts. **Can I use this Actor from my own code?** Yes. Use the Apify API or one of the official SDKs (Node.js: `apify-client`, Python: `apify-client`). The Console shows ready-to-paste code samples on the API tab. **How does billing know a video failed?** Billing fires on an explicit per-comment charge event, not on dataset writes. The Actor only fires it when a comment is delivered, so `success: false` records sit in your dataset for free. You get every result in one place and still branch on `success` and `code`, with a `request_id` for support correlation. ### Found a bug or want a feature? Open an issue on this Actor's Issues tab and include the `request_id` from any error record you saw. We respond within one business day. # Actor input Schema ## `videoUrl` (type: `string`): A single YouTube video. Accepts a watch URL (https://www.youtube.com/watch?v=...), a Shorts URL, a youtu.be link, or a bare 11-character video ID. A video that can't be found or has comments turned off comes back as a success:false record, not a rejected run. ## `videoUrls` (type: `array`): List of video URLs or IDs. Merged with videoUrl and de-duplicated; up to 50 unique videos are processed per run. A video with comments off comes back as a success:false record, so one bad video never blocks the batch. ## `maxComments` (type: `integer`): Maximum number of comment rows to return per video, counting top-level comments and (when Include replies is on) replies together. The Actor walks the comment thread page by page until it reaches this many or the thread is exhausted. ## `sort` (type: `string`): Order comments by Top (most relevant) or Newest first. ## `includeReplies` (type: `boolean`): Also fetch nested replies. Reply rows carry reply\_level 1+ and parent\_comment\_id. Off by default because replies add extra requests and count toward maxComments. ## Actor input object example ```json { "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "maxComments": 50, "sort": "top", "includeReplies": false } ``` # Actor output Schema ## `comments` (type: `string`): One record per comment (and per reply when Include replies is on). success:true carries the comment and video fields; success:false carries the error code and message for a video that failed. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "maxComments": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("apihq/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "maxComments": 50, } # Run the Actor and wait for it to finish run = client.actor("apihq/youtube-comments-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "maxComments": 50 }' | apify call apihq/youtube-comments-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=apihq/youtube-comments-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Comments Scraper", "description": "Export YouTube comments and replies to JSON by video URL or ID. Comments-off or deleted videos return success:false, cost $0, and never break the batch. One record per comment with author, likes, replies, and timestamp. $0.40 per 1,000 comments.", "version": "0.1", "x-build-id": "RQP4PV51xnX4YW2pD" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/apihq~youtube-comments-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-apihq-youtube-comments-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/apihq~youtube-comments-scraper/runs": { "post": { "operationId": "runs-sync-apihq-youtube-comments-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/apihq~youtube-comments-scraper/run-sync": { "post": { "operationId": "run-sync-apihq-youtube-comments-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "videoUrl": { "title": "Video URL or ID", "type": "string", "description": "A single YouTube video. Accepts a watch URL (https://www.youtube.com/watch?v=...), a Shorts URL, a youtu.be link, or a bare 11-character video ID. A video that can't be found or has comments turned off comes back as a success:false record, not a rejected run." }, "videoUrls": { "title": "Multiple videos", "type": "array", "description": "List of video URLs or IDs. Merged with videoUrl and de-duplicated; up to 50 unique videos are processed per run. A video with comments off comes back as a success:false record, so one bad video never blocks the batch.", "items": { "type": "string" } }, "maxComments": { "title": "Max comments per video", "type": "integer", "description": "Maximum number of comment rows to return per video, counting top-level comments and (when Include replies is on) replies together. The Actor walks the comment thread page by page until it reaches this many or the thread is exhausted." }, "sort": { "title": "Sort by", "enum": [ "top", "newest" ], "type": "string", "description": "Order comments by Top (most relevant) or Newest first.", "default": "top" }, "includeReplies": { "title": "Include replies", "type": "boolean", "description": "Also fetch nested replies. Reply rows carry reply_level 1+ and parent_comment_id. Off by default because replies add extra requests and count toward maxComments.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```