# YouTube Intelligence & Transcript Scraper (with AI Insights) (`za_intelligence/youtube-intelligence`) Actor

The all-in-one YouTube scraper that extracts full transcripts, viewer comment sentiment, creator contact emails, commercial sponsorships, video chapters, and AI-powered intelligence — all in a single run.

- **URL**: https://apify.com/za_intelligence/youtube-intelligence.md
- **Developed by:** [Aytada Intelligence](https://apify.com/za_intelligence) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 scrape onlies

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 🚀 YouTube Intelligence & Transcript Scraper (with AI Insights & Sponsorships)

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue?logo=apify)](https://apify.com)
[![Pay-Per-Event](https://img.shields.io/badge/Pricing-Pay--Per--Event-green)](https://apify.com)
[![AI Engine](https://img.shields.io/badge/AI-Gemini%203.8%20Flash-orange?logo=google)](https://apify.com)
[![No BYOK Needed](https://img.shields.io/badge/OpenRouter-Pre--Configured-brightgreen)](https://apify.com)
[![Playwright Powered](https://img.shields.io/badge/Browser-Playwright%20Chromium-red?logo=playwright)](https://playwright.dev)

> **The all-in-one YouTube scraper that extracts full transcripts, viewer comment sentiment, creator contact emails, commercial sponsorships, video chapters, and AI-powered intelligence — all in a single run.**

Stop wasting hours watching lengthy videos or parsing raw transcripts manually. Whether you are conducting competitor research, hunting for influencer marketing leads, tracking brand sentiment, or summarizing podcasts, this Actor turns any YouTube video into structured, actionable intelligence.

***

### 🌟 Why This Actor Beats Traditional YouTube Scrapers

| Feature | Standard YouTube Scrapers | **This Actor** |
| :--- | :---: | :---: |
| **Full Timed Transcripts** | ⚠️ Often breaks or blocked | ✅ **Dual-engine (XML + Playwright DOM fallback)** |
| **Videos Without Captions** | ❌ Fails with error | ✅ **Zero-Failure Fallback (extracts comments & metadata)** |
| **AI Content Intelligence** | ❌ None | ✅ **Gemini 3.8 Flash (Summaries, Genre, Tone, Topics)** |
| **Target Entity Tracking** | ❌ None | ✅ **Track custom people/brands with Yes/No & quotes** |
| **Commercial & Ad Deals** | ❌ None | ✅ **Detects sponsors, promo codes, URLs & storefronts** |
| **Audience Sentiment** | ❌ None or basic text dump | ✅ **Weighted sentiment score based on comment likes** |
| **Lead Generation** | ❌ None | ✅ **Extracts verified emails & social channels** |
| **Video Duration & Dates** | ⚠️ Inconsistent strings | ✅ **Formatted durations, seconds, & exact ISO dates** |
| **Interactive Chapters** | ❌ Missing | ✅ **Full markers with start seconds & timestamps** |
| **Pricing Model** | 💰 Flat fee / High compute | 💎 **Pay-Per-Event ($0.005 scrape / $0.015 AI)** |

***

### ⚡ Core Features & Capabilities

#### 🎙️ 1. Bulletproof Transcript & Caption Extraction

- Extracts full, timestamped captions in your preferred language code (`en`, `es`, `fr`, `de`, etc.).
- Returns both structured segment arrays (`start`, `text`) and a merged plain-text transcript (`transcriptMerged`).
- Built with a **resilient dual-layer architecture**: tries high-speed native player XML first, falling back to dynamic Playwright DOM density heuristics.

#### 🤖 2. Deep AI Video Analysis (Gemini 3.8 Flash)

- **Executive Summary:** High-impact 2–3 sentence overview of the video's core focus and takeaways.
- **Classification & Taxonomy:** Automatically identifies primary `videoType` (Podcast, Interview, Tutorial, Comedy, Sports) and specific `genre` / sub-genres.
- **Emotional Dynamics & Tone:** Detects dominant emotional tone, atmosphere, and rates **Anger Level** (`None`, `Low`, `Moderate`, `High`).
- **Target Audience & Safety:** Evaluates viewer demographics, content maturity/safety ratings, and spoken accents/dialects.
- **Valuable Insights:** Highlights standout quotes, hook strength, viral drivers, and viewer appeal.

#### 🎯 3. Custom Target Entity & Brand Mention Verification

- Pass a list of target entities (e.g. `["Tesla", "Rowan Atkinson", "Notion", "Shopify"]`).
- For every entity, the Actor produces:
  - **Mention Status:** Clear Boolean (`Yes` / `No`).
  - **Mention Type:** `Primary Subject`, `Direct Spoken Reference`, `Guest / Featured Person`, `Critical Discussion`, `Praise / Endorsement`, `Casual Reference`, or `Sponsor / Ad`.
  - **Sentiment & Context:** Evaluates how the entity was spoken about (Positive, Negative, Neutral, Mixed).
  - **Direct Evidence Quote:** Exact line from spoken dialogue, description, or top comments.

#### 💼 4. Commercial & Sponsorship Intelligence

- **Paid Sponsorship Detection:** Distinguishes between genuine commercial partnerships (host-read ads, sponsor shoutouts) and casual, organic product mentions.
- **Sponsor Dossier:** Extracts brand name, product/service promoted, sponsorship placement type, promo codes, discount URLs, and host ad-read quotes.
- **Native Badges:** Detects YouTube's official `"Includes paid promotion"` indicator.
- **Creator Storefronts & Merch:** Identifies links to Shopify, Teespring, Patreon, Fourthwall, BuyMeACoffee, and donation pages.

#### 💬 5. Audience Reception & Weighted Comment Sentiment

- Scrapes top comments (up to 100, configurable) along with middle vote/like counts and creator engagement badges (`PINNED`, `CREATOR HEART`).
- Calculates a **Normalized Audience Sentiment Score** (scale `-1.0` to `+1.0`) weighted by comment upvotes.
- Summarizes consensus themes, praise points, critical pushback, and audience mood.

#### 📧 6. Influencer Outreach & Lead Generation

- Automatically scans channel descriptions for verified **business inquiry email addresses**.
- Categorizes all external social profiles (Twitter/X, Instagram, TikTok, LinkedIn, Discord, Spotify, Telegram).

#### 📑 7. Chapters & Timestamp Navigation

- Extracts all video markers and chapters with titles, formatted timestamps (`12:45`), and exact starting seconds (`765`).

#### 🛡️ 8. Zero-Failure Non-Captioned Video Fallback

- If a video lacks captions (e.g. music videos, silent tutorials, animations, or uncaptioned live streams), the Actor **does not fail**.
- It extracts all metadata, duration, dates, chapters, channel links, and viewer comments.
- When AI analysis is enabled, Gemini deduces video content, topics, entities, and sentiment directly from the available textual data!

***

### 🎯 Ideal Use Cases

- 🔍 **Competitor & Market Intelligence:** Track brand mentions, monitor competitor announcements, and analyze viewer sentiment in comments.
- 🤝 **Influencer Marketing & Sponsorship Sourcing:** Find creator business emails, see which brands are sponsoring channels in your niche, and track promo codes.
- 📢 **Brand Reputation & PR Crisis Tracking:** Detect audience backlash, evaluate anger levels in comments, and track brand sentiment over time.
- 📚 **Research, Education & Content Summarization:** Turn 2-hour podcasts, keynote speeches, or tutorials into concise executive briefs and key quotes in seconds.
- 📈 **SEO & Trend Identification:** Discover high-performing video topics, viral hooks, and viewer questions from YouTube search queries.

***

### ⚙️ Input Configuration

The actor can be configured using simple JSON or the Apify Console UI:

| Field | Type | Default | Description |
| :--- | :--- | :---: | :--- |
| `runMode` | String | `"discover"` | **Required.** Operating mode: `"discover"` (search YouTube) or `"scrape"` (scrape specific video IDs). |
| `discoverConfig` | Object | `{}` | Settings for Discover Mode (search queries, filters, limits). |
| `scrapeConfig` | Object | `{}` | Settings for Scrape Mode (list of video IDs). |
| `lang` | String | `"en"` | Preferred language code for transcript extraction (`en`, `es`, `fr`, etc.). |
| `enableAnalysis` | Boolean | `true` | Enable AI video analysis using Gemini 3.8 Flash (OpenRouter). |
| `maxComments` | Integer | `30` | Number of top comments to scrape and analyze (0 to 100). Set to `0` to skip comments. |
| `targetEntities` | Array | `[]` | List of specific people, brands, companies, or topics to verify for mentions. |

> \[!NOTE]
> **No API Key Setup Required:** The OpenRouter AI integration is pre-configured in the Apify Actor environment. You do not need to provide your own API key.

***

#### `discoverConfig` Settings (Discover Mode)

Find videos on YouTube automatically using keyword search and powerful filters:

| Field | Type | Default | Description |
| :--- | :--- | :---: | :--- |
| `searchQueries` | Array | `["rugby highlights"]` | **Required.** List of search terms to find videos. The actor uses the first term. |
| `searchCategory` | String | `"Sport"` | Optional category keyword to append (`"Sport"`, `"News"`, `"Music"`, `"Gaming"`, `"Education"`, or `""`). |
| `uploadDate` | String | `""` | Filter by upload date: `"Hour"`, `"Today"`, `"This week"`, `"This month"`, `"This year"`. |
| `videoDuration` | String | `""` | Filter by duration: `"Short (<4 mins)"`, `"Medium (4–20 mins)"`, `"Long (>20 mins)"`. |
| `maxResultsPerQuery` | Integer | `5` | Maximum number of videos to discover and scrape. |

***

#### `scrapeConfig` Settings (Scrape Mode)

Scrape an explicit list of YouTube videos directly:

| Field | Type | Default | Description |
| :--- | :--- | :---: | :--- |
| `videoIDs` | Array | `["xZCbAki4puY"]` | **Required.** Array of YouTube video IDs or full URLs (e.g. `"xZCbAki4puY"` or `"https://youtu.be/xZCbAki4puY"`). |

***

### 📋 Input Examples

#### Example 1: Discover Mode with Duration Filter & Target Entity Tracking

```json
{
  "runMode": "discover",
  "discoverConfig": {
    "searchQueries": ["artificial intelligence podcast"],
    "uploadDate": "This month",
    "videoDuration": "Long (>20 mins)",
    "maxResultsPerQuery": 3
  },
  "enableAnalysis": true,
  "maxComments": 40,
  "targetEntities": ["OpenAI", "Anthropic", "Google", "DeepMind"],
  "lang": "en"
}
```

#### Example 2: Scrape Specific Video IDs with Sponsorship & Lead Extraction

```json
{
  "runMode": "scrape",
  "scrapeConfig": {
    "videoIDs": [
      "https://www.youtube.com/watch?v=IkhmdTqSvJw",
      "TTZi27cPRsg"
    ]
  },
  "enableAnalysis": true,
  "maxComments": 50,
  "targetEntities": ["Eric Weinstein", "Pentagon", "David Grusch"]
}
```

***

### 📊 Target Entity Tracking Output Example

When you pass `targetEntities: ["Rowan Atkinson", "Tesla"]`, the Actor evaluates each entity with surgical precision:

```json
[
  {
    "entity": "Rowan Atkinson",
    "mentioned": true,
    "mentionedStatus": "Yes",
    "mentionType": "Primary Subject",
    "sentiment": "Positive",
    "context": "Main focus of the video celebrating his iconic comedic timing and legendary perfectionism on set.",
    "evidenceOrQuote": "Rowan Atkinson was an absolute perfectionist who crafted every gesture meticulously."
  },
  {
    "entity": "Tesla",
    "mentioned": false,
    "mentionedStatus": "No",
    "mentionType": "Not Mentioned",
    "sentiment": "N/A",
    "context": "Entity was not mentioned in the dialogue, description, chapters, or top viewer comments.",
    "evidenceOrQuote": ""
  }
]
```

***

### 📦 Output Dataset Structure

Results are stored in the default dataset and viewable directly in the **Storage / Output** tab as tables, JSON, or CSV:

| Field | Type | Description |
| :--- | :--- | :--- |
| `videoId` | String | Unique YouTube video identifier (e.g. `IkhmdTqSvJw`). |
| `title` | String | Full title of the YouTube video. |
| `channel` | String | Channel name. |
| `subscribers` | String | Channel subscriber count (e.g. `"2.4M subscribers"`). |
| `views` | String | Total view count (e.g. `"6,480,565 views"`). |
| `likes` | String | Total like count (e.g. `"31K"`). |
| `videoDuration` | String | Formatted duration (e.g. `"1:02:05"` or `"3:33"`). |
| `videoDurationSeconds` | Integer | Total duration in integer seconds (e.g. `3725`). |
| `uploadDate` | String | Video upload timestamp (exact ISO timestamp or formatted date). |
| `commentsCount` | String | Total count of comments reported on YouTube. |
| `scrapedCommentsCount` | Integer | Number of top comments scraped and analyzed for this video. |
| `commentSentimentOverall` | String | Audience consensus sentiment (e.g. `"Overwhelmingly Positive"`, `"Critical / Divided"`). |
| `commentSentimentScore` | String | Normalized audience score (e.g. `"+0.85"`, scale `-1.0` to `+1.0`). |
| `commentSentimentSummary` | String | 2–3 sentence executive summary of viewer discussion and consensus. |
| `commentsSentiment` | String | Detailed JSON object with % breakdown, key liked themes, and representative quotes. |
| `description` | String | Full, clean YouTube video description. |
| `hasSpeech` | Boolean | Whether spoken dialogue/speech was detected in the video or transcript. |
| `hasPaidSponsorship` | Boolean | Whether commercial sponsorships or paid ads were detected. |
| `paidPromotionBadge` | Boolean | Whether YouTube's native "Includes paid promotion" overlay is active. |
| `sponsors` | String | JSON array of sponsors (brand, product, placement type, promo code, URL, quotes). |
| `contactEmails` | String | Verified creator contact email addresses extracted from description. |
| `socialLinks` | String | JSON object of categorized social profiles (Twitter, Instagram, TikTok, LinkedIn, Discord). |
| `shopAndMerch` | String | JSON object of storefront and donation links (Shopify, Teespring, Patreon, etc.). |
| `commercialIntelligence` | String | Full commercial dossier detailing sponsorships, organic mentions, and monetization. |
| `hasChapters` | Boolean | Whether the video contains chapter timestamps. |
| `chaptersCount` | Integer | Total number of chapters detected. |
| `chapters` | String | JSON array of video chapters (`title`, `time`, `startSeconds`). |
| `videoType` | String | AI Classification (e.g. `"Podcast"`, `"Documentary"`, `"Comedy Compilation"`). |
| `genre` | String | AI Genre and sub-genres. |
| `sentiment` | String | Overall narrative sentiment. |
| `emotionalTone` | String | Dominant verbal and emotional tone (e.g. `"Analytical debate"`, `"Lighthearted"`). |
| `angerLevel` | String | Hostility / anger rating (`"None"`, `"Low"`, `"Moderate"`, `"High"`). |
| `positiveMentions` | String | JSON array of people, products, or things praised or spoken about favorably. |
| `negativeMentions` | String | JSON array of people, products, or things criticized or spoken about unfavorably. |
| `entitySentimentAnalysis` | String | Granular breakdown of each entity: sentiment, manner of discussion, and quotes. |
| `targetEntitiesSummary` | String | Quick summary of target entity check (`"Rowan Atkinson: Yes | Tesla: No"`). |
| `targetEntityMatches` | String | Complete JSON array evaluating every target entity with full verification details. |
| `summary` | String | AI Executive Summary of the video content. |
| `people` | String | JSON array of featured people (`name`, `role`, `category`, `context`). |
| `entities` | String | Categorized entities (`people`, `companies`, `products`, `places`, `institutions`). |
| `keyTopics` | String | JSON array of key topics and core themes discussed. |
| `targetAudience` | String | Intended audience demographic and interest profile. |
| `contentSafety` | String | Content safety rating and maturity observations. |
| `languageAndDialect` | String | Primary spoken language and dialect/accent. |
| `valuableInsights` | String | Standout highlights, quotes, hook strength, and virality factors. |
| `analysis` | String | Complete structured Gemini AI analysis in JSON format. |
| `transcriptMerged` | String | Full merged transcript text block. |
| `comments` | String | JSON array of scraped comment objects (author, text, likes, likeCount, pinned, hearted). |
| `_chargeStatus` | String | Transparent status of Pay-Per-Event charges for this video. |
| `error` | String | Error message if scraping failed (or empty if successful). |

***

### 💰 Transparent Pay-Per-Event (PPE) Pricing

This Actor utilizes Apify's **Pay-Per-Event (PPE)** pricing model. You never pay high flat fees or waste credits on failed runs. You pay only for what you successfully retrieve:

| Event Name | Event Title | Price | Description |
| :--- | :--- | :---: | :--- |
| **`video-data-retrieved`** | Video Data Retrieved | **$0.005** / video | Charged **per video** when metadata, duration, dates, captions/transcript (if available), chapters, and comments (if requested) are successfully scraped. |
| **`ai-video-analysis`** | AI Video Analysis | **$0.015** / video | Charged **per video** when AI analysis is enabled (`enableAnalysis: true`) and successfully extracts deep intelligence (summary, sentiment, entities, sponsorships, audience reaction). |

> \[!TIP]
> **Budget Control:** If you only need raw transcripts and metadata without AI, set `enableAnalysis: false`. You will only be billed `$0.005` per video!

***

### ❓ Frequently Asked Questions (FAQ)

<details>
<summary><strong>Do I need my own OpenRouter or Gemini API key?</strong></summary>

**No.** The AI analysis engine is fully integrated and managed within the Apify environment. You don't need to create an OpenRouter account, subscribe to external services, or manage billing keys. It works right out of the box.

</details>

<details>
<summary><strong>What happens if a video has no captions or transcript?</strong></summary>

Unlike other scrapers that crash or fail, this Actor features an automatic **Zero-Failure Fallback**. It retrieves all video metadata, comments, chapters, and description. When AI analysis is enabled, Gemini analyzes the video using the title, description, chapters, and community discussion.

</details>

<details>
<summary><strong>How many comments can I scrape?</strong></summary>

You can configure `maxComments` between `0` and `100` (default is `30`). Set it to `0` if you want maximum scraping speed and don't need viewer comments.

</details>

<details>
<summary><strong>Can I export data to Excel or Google Sheets?</strong></summary>

**Yes!** Apify allows one-click export of your dataset to JSON, CSV, Excel (XLSX), XML, or HTML, and provides webhooks and REST API endpoints to feed the data directly into your CRM, database, or automated workflow.

</details>

***

### 🤝 Support & Feedback

If you have feature requests, notice any issues, or want custom integrations, please reach out via the **Issues** tab on Apify Console. We actively maintain and enhance this Actor!

# Actor input Schema

## `runMode` (type: `string`):

Choose whether to discover videos by search or scrape specific video URLs.

## `discoverConfig` (type: `object`):

Settings used when discovering videos via YouTube search.

## `scrapeConfig` (type: `object`):

Settings used when scraping known YouTube videos directly.

## `lang` (type: `string`):

Preferred language code for transcript extraction (e.g. en, fr, es).

## `enableAnalysis` (type: `boolean`):

Analyze video type, genre, sentiment, featured people, and key themes using Gemini 3.8 Flash.

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

Number of top comments to scrape and analyze for audience sentiment (set to 0 to skip comments).

## `targetEntities` (type: `array`):

Enter names of people, brands, products, companies, or topics to verify if they were mentioned in the video (returns boolean Yes/No, mention type, context, and evidence).

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

Select proxy group to avoid YouTube IP blocks and bot-detection during scraping.

## Actor input object example

```json
{
  "runMode": "discover",
  "lang": "en",
  "enableAnalysis": true,
  "maxComments": 5,
  "targetEntities": [],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Complete dataset of scraped YouTube videos with metadata, transcripts, and AI intelligence.

# 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 = {
    "maxComments": 5,
    "targetEntities": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("za_intelligence/youtube-intelligence").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 = {
    "maxComments": 5,
    "targetEntities": [],
}

# Run the Actor and wait for it to finish
run = client.actor("za_intelligence/youtube-intelligence").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 '{
  "maxComments": 5,
  "targetEntities": []
}' |
apify call za_intelligence/youtube-intelligence --silent --output-dataset

```

## MCP server setup

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

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/185aV5gMysaZXJy3W/builds/HT8AFfLH8sL4akejB/openapi.json