# YouTube Comment Voice-of-Customer Miner (`mibedk/youtube-comment-voc-miner`) Actor

Pulls comments and replies from YouTube videos matching a brand, product, or keyword, via the official YouTube Data API v3, structured for sentiment and voice-of-customer analysis.

- **URL**: https://apify.com/mibedk/youtube-comment-voc-miner.md
- **Developed by:** [Mikkel Bech-Hansen](https://apify.com/mibedk) (community)
- **Categories:** Lead generation, Videos, Social media
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 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 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 Comment Voice-of-Customer Miner

Pulls the comments and replies people actually leave on YouTube videos about a brand, product, or topic, so you can read (or run sentiment analysis on) what customers really think — without scraping the YouTube website. It talks to Google's official YouTube Data API v3, the same API YouTube itself is built on, so there's no anti-bot cat-and-mouse and no login required.

You either point it at specific videos, or give it a search topic and it finds the top matching videos itself. Every comment can optionally be filtered down to only the ones mentioning your keywords (a brand name, a feature, a competitor) before it's saved.

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `apiKey` | string (secret) | *(required)* | Your free YouTube Data API v3 key. Get one at [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) → Create Credentials → API key, then enable **YouTube Data API v3** for that project in the API Library. Takes about 2 minutes, no billing account required. |
| `videoUrls` | array of strings | `[]` | Explicit videos to mine, as full URLs (`https://www.youtube.com/watch?v=...`) or bare 11-character video IDs. If empty, `searchQuery` is used to discover videos instead. |
| `searchQuery` | string | `"iPhone 16 review"` | Brand/product/topic to search YouTube for. Only used when `videoUrls` is empty. |
| `keywordFilter` | array of strings | `[]` | Only keep comments/replies containing at least one of these words or phrases (case-insensitive). Leave empty to keep everything. |
| `includeReplies` | boolean | `true` | Also fetch replies to top-level comments. |
| `sortOrder` | `"relevance"` | `"time"` | `"relevance"` | `relevance` = YouTube's top comments first. `time` = newest first, good for monitoring fresh reactions. |
| `maxItems` | integer | `100` | Hard cap on total comments/replies returned and charged for, across the whole run. |
| `maxVideos` | integer | `5` | When discovering videos via `searchQuery`, how many candidate videos to pull comments from (1–50). Ignored when `videoUrls` is set. |
| `proxyConfiguration` | object | `{ "useApifyProxy": false }` | Optional. The actor talks directly to Google's API, not youtube.com, so a proxy is rarely needed. |

The default input runs with zero changes except pasting in your own `apiKey` — it searches "iPhone 16 review" and returns up to 30 comments from up to 3 videos.

### Output

One dataset record per matching comment or reply:

```json
{
  "videoId": "aaaaaaaaaa1",
  "videoTitle": "iPhone 16 Review: Is It Worth It?",
  "videoUrl": "https://www.youtube.com/watch?v=aaaaaaaaaa1",
  "commentId": "c1",
  "parentId": null,
  "isReply": false,
  "authorDisplayName": "alice",
  "authorChannelUrl": "https://www.youtube.com/channel/alice",
  "textOriginal": "The battery life on this thing is amazing",
  "likeCount": 12,
  "publishedAt": "2026-08-01T00:00:00Z",
  "updatedAt": "2026-08-01T00:00:00Z",
  "matchedKeywords": ["battery"],
  "commentUrl": "https://www.youtube.com/watch?v=aaaaaaaaaa1&lc=c1"
}
```

`parentId` is `null` for top-level comments and the parent comment's ID for replies. `matchedKeywords` lists which of your `keywordFilter` terms matched (empty array if no filter was set).

### Cost

This actor uses pay-per-event pricing:

| Event | Price | When it's charged |
|---|---|---|
| `comment-scraped` | $0.003 | Once per comment or reply saved to the dataset. |
| `video-searched` | $0.005 | Once per video discovered via `searchQuery` (not charged when you supply `videoUrls` directly). |

A typical run pulling 100 comments from 5 videos found via search costs about 100 × $0.003 + 5 × $0.005 = **$0.325**. Supplying `videoUrls` directly and skipping search cuts that to $0.30 for the same 100 comments. The run stops cleanly (not with an error) if it hits your configured `ACTOR_MAX_TOTAL_CHARGE_USD` cap partway through — whatever was collected up to that point is kept.

### Known limitations

- **Reply depth**: only the replies YouTube inlines with each comment thread (typically the first few, most-relevant ones) are returned. Very long reply chains are not fully paginated in this version.
- **Comments disabled / held for review**: videos with comments turned off, or where all comments are pending moderator approval, return nothing for that video — this is logged as a warning, not an error, and the run continues with the other videos.
- **Free API quota**: Google's free tier is 10,000 units/day; a `commentThreads.list` call costs 1 unit and a `search.list` call costs 100 units, so heavy `searchQuery` use burns quota faster than supplying `videoUrls` directly. High-volume users may need to request a quota increase from Google (free, self-service) or shard across API keys.
- **No sentiment scoring**: this actor returns raw comment text and metadata, not a sentiment label — pair it with your own analysis or a downstream LLM/NLP step.
- **Public data only**: no OAuth, so it can only see what's publicly visible on YouTube — no access to a channel's private comment moderation queue.

### Legal

This Actor is an independent, third-party tool. It is not affiliated with, endorsed
by, or sponsored by YouTube or Google, and it uses the official **YouTube API
Services**.

By using this Actor you agree to comply with the [YouTube API Services Terms of
Service](https://www.youtube.com/t/terms) and the [Google Privacy
Policy](https://policies.google.com/privacy), which govern any data retrieved
through the YouTube Data API v3. In particular: do not retain cached API data
longer than permitted (generally, refresh or delete it within 30 days unless
you have a separate right to keep it), do not use the data to build a product
that replicates or competes with core YouTube functionality, and honor deletion
if a video, comment, or channel is removed from YouTube. You are responsible
for your own use of the data this Actor returns.

# Actor input Schema

## `apiKey` (type: `string`):

A free Google Cloud API key with the 'YouTube Data API v3' enabled. No OAuth or login needed. Get one in ~2 minutes: console.cloud.google.com/apis/credentials -> Create Credentials -> API key, then enable 'YouTube Data API v3' for that project in the API Library. The free daily quota (10,000 units) covers roughly 1,000+ comment-list calls per day.

## `videoUrls` (type: `array`):

Explicit YouTube videos to mine comments from. Accepts full URLs or bare 11-character video IDs. Leave empty to discover videos automatically via 'Search query' instead.

## `searchQuery` (type: `string`):

A brand, product, or topic to search YouTube for. The actor finds the top matching videos (see 'Max videos to search') and mines comments from each. Ignored if 'Video URLs' is filled in.

## `keywordFilter` (type: `array`):

Only keep comments/replies containing at least one of these words or phrases (case-insensitive substring match). Leave empty to keep every comment returned by YouTube.

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

Also fetch and return replies to top-level comments, not just the top-level comments themselves.

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

'relevance' returns YouTube's top comments first (best for a quick read on sentiment). 'time' returns newest comments first (best for monitoring fresh reactions).

## `maxItems` (type: `integer`):

Hard cap on the total number of comment records returned and charged for across the whole run.

## `maxVideos` (type: `integer`):

When discovering videos via 'Search query' (i.e. Video URLs is empty), how many candidate videos to pull comments from. Ignored when Video URLs is filled in.

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

Optional. The actor talks directly to Google's API, not YouTube's website, so a proxy is rarely needed and the run is cheaper without one. Leave this off unless you are hitting IP-based rate limits.

## Actor input object example

```json
{
  "videoUrls": [],
  "searchQuery": "iPhone 16 review",
  "keywordFilter": [],
  "includeReplies": true,
  "sortOrder": "relevance",
  "maxItems": 100,
  "maxVideos": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `comments` (type: `string`):

No description

# 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 = {
    "videoUrls": [],
    "keywordFilter": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("mibedk/youtube-comment-voc-miner").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 = {
    "videoUrls": [],
    "keywordFilter": [],
}

# Run the Actor and wait for it to finish
run = client.actor("mibedk/youtube-comment-voc-miner").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 '{
  "videoUrls": [],
  "keywordFilter": []
}' |
apify call mibedk/youtube-comment-voc-miner --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mibedk/youtube-comment-voc-miner"
        }
    }
}

```

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/4eVy9BinYdMp1i4U5/builds/lOH4xZXPLipknFOfz/openapi.json