YouTube Market Intelligence

YouTube Market Intelligence searches YouTube for one keyword, selects distinct matched videos in the requested order, and enriches each successful match with public video and channel details. The result is a structured Dataset for research, review, and carefully governed analysis—not a promise that every match contains every field.

• Search by one required keyword using relevance, view count, rating, or upload-date ordering.
• Collect up to 10,000 distinct matched video tasks with usable channel handles.
• Receive 37 top-level fields covering video metadata, channel metrics, public links, and description-derived emails.
• Run from Apify Console, API clients, schedules, webhooks, or MCP-capable workflows.

Why Choose This API

YouTube search pages and channel About surfaces split useful context across multiple responses. This Actor combines those steps. It first streams search matches, ignores entries without a usable channel handle, removes duplicate video IDs, and stops when max_results tasks have been collected. It then visits each matching video's channel and video surfaces to build one combined row when at least one enrichment path succeeds.

That distinction matters: max_results is a task limit, not a guaranteed number of Dataset rows. A removed video, unavailable channel, changed page response, timeout, or extractor failure can make a task produce no row. Conversely, the same channel can appear more than once when different videos from that channel match the keyword. Runtime deduplicates video IDs, not channel IDs.

The Actor does not require you to supply a YouTube Data API key. It reads current public web responses through its configured extraction paths. Public-page shapes and search ordering can change without notice, and fields such as likes, comments, country, joined date, tags, banners, or verification may be absent. Metrics are snapshots captured at processed_at, not audited historical facts.

Use this tool when a joined video-and-channel row is more useful than raw search cards. It is especially convenient for exploratory niche mapping, content inventories, channel discovery, and review queues. It is not a bulk messaging system, identity-resolution service, transcript scraper, comment scraper, or guarantee of creator contact data.

Quick Start Guide

Open the Actor, provide all three required inputs, and start the run. A one-result smoke test is:

{
  "keyword": "OpenAI",
  "sort_by": "relevance",
  "max_results": 1
}

After completion, inspect the run status and open the default Dataset. A SUCCEEDED run can still contain fewer rows than requested, including zero, because expected extraction failures are skipped. Keep the defaultDatasetId returned by Apify; it is the identifier used for downloads and subsequent API reads.

For release verification, select an exact build number rather than relying on latest, cap total charge, request one result, and read both the Dataset and the INPUT record from the run's default key-value store. This checks the deployed schema and the real data path instead of treating a green build alone as proof.

Input Parameters

keyword is required text. Runtime checks that it is a string and not whitespace-only, then passes the original submitted value to YouTube search. A specific phrase usually produces a more reviewable sample than a broad word. Search results are current and can vary with YouTube changes; the Actor does not guarantee stable ranking across runs.

sort_by is required and must equal relevance, view_count, rating, or upload_date. These names are exact and case-sensitive. They select the current ordering requested from the underlying YouTube search path. YouTube's search filter documentation describes user-facing filtering concepts, but this Actor exposes only the four runtime-supported sort values.

max_results is a required integer from 1 to 10,000 in the public schema. Runtime collects distinct video IDs that also have a usable channel handle. Search cards without a handle do not count, duplicate video IDs do not count twice, and collection stops at the limit. Enrichment then runs sequentially. Each task has a long internal timeout, while the AgentX Actor also has a twelve-hour platform timeout, so very large requests may not finish.

No optional field changes geography, language, date range, channel deduplication, or contact behavior. If you need multiple keywords, start separate bounded runs and attach your own query identifier after export.

Output Data Schema

Each successful row exposes 37 top-level fields. Video fields include URL, ID, thumbnail, title, description, duration, publication timestamp, categories, tags, views, likes, dislikes, comments, dimensions, frame rate, audio title, and audio artist. Channel fields include ID, name, handle, URL, joined date, country, description, tags, public external links, description-derived email strings, avatar, banner, verification flag, RSS URL, subscribers, channel views, and channel video count. processor and processed_at record provenance.

Nested channel_links entries can contain title, url, domain, and favicon_url, which is why an MCP client may report more flattened field paths than the 37 top-level schema fields. Lists are merged and deduplicated when both channel extraction paths return values. Missing scalars can be null, and unavailable lists can be empty.

contact_emails is not a hidden business-email unlock. Runtime applies an email pattern to public channel description text. The list can be empty, can contain a general address, and can contain text that is stale or unsuitable for outreach. Verify ownership, relevance, consent, and applicable communications law independently.

A shortened row looks like this:

{
  "video_id": "example123",
  "video_title": "Example topic overview",
  "video_url": "https://www.youtube.com/watch?v=example123",
  "video_view_count": 125000,
  "channel_id": "UCexample",
  "channel_name": "Example Channel",
  "channel_handle": "@example",
  "channel_url": "https://www.youtube.com/@example",
  "subscriber_count": 42000,
  "channel_links": [],
  "contact_emails": [],
  "processed_at": "2026-07-24T03:42:50+00:00"
}

Integration Examples

Call Actor ID gCHgOwrCrCYYOcqia or agentx/youtube-market-intelligence. In Python, create an ApifyClient, call the Actor with run_input, then iterate items from run["defaultDatasetId"]. In JavaScript, call the Actor and list items from run.defaultDatasetId. Keep tokens in environment variables or a secret manager, not in committed code or shared screenshots.

For a recent-order research job, the body can be:

{
  "keyword": "robotics tutorial",
  "sort_by": "upload_date",
  "max_results": 25
}

Schedules can produce periodic snapshots. Webhooks can notify a downstream queue when the run reaches a terminal state. MCP clients should fetch Actor details first, submit schema-valid input, poll the run, and read Dataset items. Always record the keyword, sort, run ID, build number, and UTC collection time because search results and channel metrics are time-sensitive.

When loading a database, use video_id as the per-video natural key only after considering repeated snapshots. Use channel_id for channel-level grouping, but do not assume one output row per channel. Preserve processed_at to compare runs, and store nested arrays as JSON or normalize them into child tables.

Pricing & Cost Calculator

Current pricing is pay per event. Actor Start costs $0.01 and can be charged even when no Dataset rows are produced. Result is charged once per successfully written row. At the current published tiers, Result costs $0.0085 on Free, $0.0076 on Bronze, $0.0068 on Silver, and $0.0060 on Gold, Platinum, or Diamond.

For one successful row, estimated Actor-event cost is $0.0185 on Free or $0.0176 on Bronze. Ten successful rows are about $0.095 on Free or $0.086 on Bronze. One hundred successful rows are about $0.86 on Free or $0.77 on Bronze. These estimates use one start event and exclude separate platform compute, storage, or transfer charges that may appear on your Apify account.

Requested tasks and billed results are not identical. If 25 tasks produce 20 rows, Result is charged for the 20 pushed rows, plus Actor Start. A charge cap can terminate work before all planned rows are written. The current Pricing tab is authoritative if prices or tier rules change.

Use Cases & Applications

Content teams can build a keyword-specific inventory of current videos, compare titles and descriptions, or select a manual review sample. Market researchers can group rows by channel_id, compare public audience metrics, and observe which channels recur across separate keyword runs. Developers can seed an internal discovery queue with video URLs, channel URLs, thumbnails, and timestamps.

Creator-research workflows can use public links and description-derived emails as leads for human verification. Do not automate unsolicited bulk outreach from these fields. A blank email list is a valid result, and an extracted address is not evidence of consent, current ownership, or a commercial relationship.

Repeated scheduled runs can support change analysis, but the Actor does not calculate deltas or maintain history for you. Save snapshots with run IDs and timestamps, then compute differences in your own warehouse. Treat views, likes, subscribers, and video counts as volatile platform metrics.

FAQ

Why did I receive fewer rows than max_results?

The limit caps valid search tasks. Enrichment can fail or time out, and a row is skipped when neither channel nor video extraction returns usable data.

Can the same channel appear multiple times?

Yes. Runtime removes duplicate video IDs but not channel IDs. Different matched videos from the same channel create separate rows when enrichment succeeds.

Does it return transcripts or comments?

No. It can return a public comment count when available, but it does not return comment bodies or transcripts.

Are contact emails guaranteed?

No. They are pattern matches found in public channel description text. Many rows have none, and every value requires independent verification and lawful use.

Why are some counts zero or null?

One extraction path can default unavailable channel counts to zero, while other missing fields remain null. Interpret absence conservatively and use the raw row context.

Does the free plan have another limit?

Runtime can block a Free, non-paying user after 20 recorded runs for this Actor outside test or web origins. Database availability and platform origin affect that check.

Trust & Certifications

The public contract documents actual runtime boundaries: three required inputs, four sort modes, 37 top-level fields, skipped failures, possible repeated channels, and event billing. Release checks should include JSON parsing, schema consistency, static analysis, source-hash comparison across mapped brands, a cloud build, an exact-build run, and independent Dataset/KVS readback.

No certification is claimed for metric accuracy, identity, email ownership, audience quality, brand safety, or regulatory suitability. YouTube can remove content, hide metrics, change markup, or revise search ranking. Historical snapshots can become stale immediately after collection.

Legal & Compliance

Review the current YouTube Terms of Service and Google Privacy Policy before operating a workflow. You are responsible for lawful collection, a valid purpose, data minimization, retention, security, and honoring rights that apply in your jurisdiction.

Do not use output to send spam, evade platform controls, manipulate engagement, profile sensitive traits, or claim a relationship that does not exist. Public availability does not remove copyright, privacy, contract, or communications-law obligations. This README is operational documentation, not legal advice.

Related Tools

YouTube Transcript focuses on transcript extraction. All Video Scraper supports broader multi-platform video discovery. Video Captions Downloader retrieves available captions.

Video Transcript, TikTok Creator API, and LinkedIn Company Lookup cover adjacent enrichment workflows. Each Actor runs independently with its own schema, coverage, pricing, and limitations.

Support & Community

For reproducible problems, contact AgentX support. Include the Actor name, run ID, UTC time, build number, sanitized input, expected behavior, actual Dataset item count, and a short relevant log excerpt. Never share an Apify token or other credentials.

Before reporting a missing field, verify the source page still exposes it publicly and inspect both the row and run logs. For zero-row runs, confirm the keyword, search collection status, charge cap, timeout, and Dataset count.

Last updated: July 23, 2026.