# YouTube Niche Finder (`truefetch/youtube-niche-finder`) Actor

Search YouTube by keyword and four sort modes, then pair each successfully enriched video with best-effort public channel details, external links, and emails detected in public descriptions. Successful rows expose 37 top-level fields; failed enrichments are skipped.

- **URL**: https://apify.com/truefetch/youtube-niche-finder.md
- **Developed by:** [TrueFetch](https://apify.com/truefetch) (community)
- **Categories:** Social media, Videos, News
- **Stats:** 13 total users, 0 monthly users, 97.2% runs succeeded, 2 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $4.50 / 1,000 results

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/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 Niche Listing** produces a joined video-and-channel dataset from a single YouTube keyword search. It collects distinct matched videos, looks up their public channel context, and writes one row only when at least one enrichment route succeeds.

- Choose one keyword and one exact ordering: relevance, view count, rating, or upload date.
- Bound collection with a required 1–10,000 matched-video task limit.
- Export 37 top-level video, channel, link, metric, and processing fields.
- Use Console runs, REST clients, schedules, webhooks, or MCP-aware agents.

### What does YouTube Niche Listing do?

The Actor turns a niche query into structured research rows. Search collection streams current YouTube results, rejects cards that lack a usable channel handle, and removes duplicate video IDs. After it reaches `max_results` or exhausts search, it processes each task in sequence. One path reads the public channel About response; another uses the current video and channel extractors. The two dictionaries are merged into a single row.

The output unit is a matched video, not a unique creator. If three videos from one channel match, the channel can appear three times. Search-task count and Dataset count are also different. A task that loses access, times out, or returns no useful profile or video data is skipped, so ten requested tasks can produce fewer than ten rows.

Successful rows can include video identity, text, publication time, engagement counters, media dimensions, channel identity, public profile text, tags, listed links, description-derived email patterns, images, RSS URL, and channel counters. Availability depends on what YouTube exposes at collection time. This Actor does not return transcript text, comment bodies, private contact data, or a verified owner identity.

### How do I run YouTube Niche Listing?

In Apify Console, open the Input tab and fill all three fields. A safe initial check requests one row:

```json
{
  "keyword": "indie game development",
  "sort_by": "relevance",
  "max_results": 1
}
```

Start the run, wait for a terminal state, and inspect the default Dataset. Also check item count: `SUCCEEDED` does not guarantee a row because expected per-task extraction failures are intentionally skipped. The default key-value store normally retains only the INPUT record.

For a production caller, save the run ID, build number, `defaultDatasetId`, and UTC collection time. A release smoke test should pin the exact new build, use one task, set a cost cap, then read Dataset and KVS through a separate API or MCP operation. That end-to-end readback catches schema or deployment drift that a local JSON check cannot.

### What data does YouTube Niche Listing return?

The Dataset schema has 37 top-level properties. Video coverage includes thumbnail, title, URL, ID, description, duration seconds, published timestamp, categories, tags, view/like/dislike/comment counters, width, height, FPS, and audio title/artist. Channel coverage includes avatar, name, handle, URL, ID, joined date, country, description, tags, external links, extracted email strings, banner, verification state, RSS URL, subscriber count, total views, and video count. `processor` and `processed_at` identify the Actor and snapshot time.

`channel_links` is an array of objects. Each object can hold a normalized title, HTTPS URL, domain, and favicon URL. Clients that flatten nested objects may therefore report 39 or more dot paths even though the public top-level contract contains 37 fields.

Email handling is intentionally limited. Runtime searches public channel description text for email-shaped strings. It does not reveal an address hidden behind a sign-in gate, validate deliverability, establish ownership, or prove consent. Empty `contact_emails` is normal. A detected string can be obsolete, general-purpose, or unrelated to your intended use.

Missing values may be null, empty arrays, or—in some extractor paths—zero for unavailable counts. A representative shortened item is:

```json
{
  "video_id": "sample456",
  "video_title": "Indie game postmortem",
  "video_url": "https://www.youtube.com/watch?v=sample456",
  "video_categories": ["Gaming"],
  "channel_id": "UCsample",
  "channel_name": "Sample Studio",
  "channel_handle": "@samplestudio",
  "channel_url": "https://www.youtube.com/@samplestudio",
  "channel_links": [],
  "contact_emails": [],
  "subscriber_count": 18000,
  "processed_at": "2026-07-24T04:00:00+00:00"
}
```

### What inputs can I use?

`keyword` must be a string containing something other than whitespace. The original value is retained after validation and sent to search. More specific phrases generally create easier-to-review result sets, but TrueFetch does not promise a stable ranking or the same matches on later runs.

`sort_by` must be exactly one of `relevance`, `view_count`, `rating`, or `upload_date`. Values are lowercase and case-sensitive. They map to the current sort choices used by runtime; there is no custom date window, country, language, channel filter, or secondary sort.

`max_results` must be an integer of at least 1, and the public schema caps it at 10,000. It is the number of distinct video IDs with usable channel handles collected for enrichment, not a minimum output quantity. Very large limits can take a long time because tasks run sequentially and each task has a long internal timeout.

For an upload-ordered batch, use:

```json
{
  "keyword": "home coffee roasting",
  "sort_by": "upload_date",
  "max_results": 20
}
```

### What platforms and markets are supported?

This Actor targets YouTube public web search and public video/channel surfaces. It does not accept other video platforms. It can encounter channels and videos from many countries, but the input has no market, locale, language, or geofence selector. A channel's `channel_country` is returned only when the public data path supplies it.

YouTube describes user-facing filtering in its [advanced search help](https://support.google.com/youtube/answer/111997), but upstream behavior can change independently of this Actor. Localized pages, restricted videos, deleted content, age gates, regional availability, and incomplete public profiles can affect results.

### Why use YouTube Niche Listing?

The main convenience is the join. A plain search response is useful for discovery but lacks much of the channel context needed for review. YouTube Niche Listing attempts both public About extraction and video/channel extraction, merges non-empty values, deduplicates list members, and produces one tabular row that can be loaded into a spreadsheet or database.

The contract is explicit about uncertainty. It does not call every email a business lead, does not label each channel a unique creator, and does not claim that `max_results` equals final rows. That makes it easier to build honest downstream quality checks.

### Who is YouTube Niche Listing for?

Researchers can map which videos and channels appear for a niche query at a particular time. Editorial teams can assemble human review queues from titles, thumbnails, descriptions, and public metrics. Data engineers can ingest snapshots and group them by `video_id` or `channel_id`.

Marketing or partnership teams may use public links as starting points for manual qualification, subject to policy and law. The Actor is not an authorization to send unsolicited messages. AI agents can use bounded runs for discovery, but should not infer sensitive traits or factual identity from a channel name, handle, email string, or content category.

### Can I use YouTube Niche Listing through an API or MCP?

Yes. Call `truefetch/youtube-niche-listing` or Actor ID `GQUd4aDw89LUD9IRZ` through Apify's REST API or official clients. The calling sequence is: start a run with JSON input, poll until terminal, then fetch items with `defaultDatasetId`. Keep the Apify token in a secret store or environment variable.

An MCP client should fetch Actor details before calling it so the required fields and current pricing are visible. After completion, use the returned storage identifiers to read Dataset items and the INPUT record. Public Actor execution can depend on the MCP session's plan; if the session cannot start it, an authorized Apify API call can run the exact build and MCP can still independently read the resulting storage when permitted.

### How much does YouTube Niche Listing cost?

Pricing is pay per event. Actor Start is $0.01 and applies when execution begins, including a run that later yields no rows. Result is charged for each successfully written matched-video row. Current Result prices are $0.0050 on Free, $0.0048 on Bronze, $0.0046 on Silver, and $0.0045 on Gold, Platinum, or Diamond.

A one-row run costs about $0.015 on Free or $0.0148 on Bronze. Twenty successful rows cost about $0.11 on Free or $0.106 on Bronze. One hundred successful rows cost about $0.51 on Free or $0.49 on Bronze. These estimates cover Actor events and do not include separate Apify compute, storage, or transfer charges.

Billing follows rows actually pushed, not merely `max_results`. Cost caps can stop work early. Free non-paying users can also encounter a runtime limit after 20 recorded runs outside test or web origins. Always consult the live Pricing tab because prices and plan behavior can change.

### How does YouTube Niche Listing compare with alternatives?

A raw YouTube search is fastest for manual browsing but does not provide this joined Dataset. The official YouTube Data API offers documented endpoints and quota rules, but requires API credentials and has its own field model. A custom scraper can be tailored precisely, while you must maintain search parsing, retries, link normalization, output storage, billing integration, and deployments yourself.

YouTube Niche Listing is appropriate when its exact three-input, 37-field contract matches the workflow. It is not the right tool when you require authenticated private data, guaranteed unique channels, historical metric series, comment bodies, transcripts, delivery-verified emails, or a stable official API schema.

### What are the limits and troubleshooting steps?

Output can shrink when search cards lack channel handles, video IDs repeat, pages are restricted, both enrichment paths fail, a task exceeds its timeout, the total run is stopped, or the charge cap is reached. Public YouTube markup can change before a new Actor release.

Start troubleshooting with a specific keyword, `relevance`, and `max_results: 1`. Confirm the deployed build and run status, read the status message, inspect Dataset count, and check the INPUT record. If a row exists but one field is missing, verify that the current public source actually shows it. Null or empty values are not automatically defects.

Large runs are sequential and can be slow. Split independent keywords into separate bounded runs rather than immediately choosing 10,000. Preserve partial successful rows if a later task fails.

### FAQ

#### Is each row a unique channel?

No. Each row represents a distinct matched video. The same channel can appear for multiple videos.

#### Does max\_results guarantee the same row count?

No. It limits collected tasks. Tasks with failed enrichment are skipped, and charge or time limits can stop processing.

#### Does the Actor expose private creator emails?

No. It only returns email-shaped strings detected in public channel description text, when present.

#### Are transcripts or comments included?

No. The schema includes neither transcript text nor comment bodies. A public comment count may be returned.

#### Why did a metric change between runs?

Views, likes, comments, subscribers, and channel totals are volatile snapshots. Search ranking and source availability can also change.

### Related TrueFetch Actors

- [YouTube Video Downloader](https://apify.com/truefetch/youtube-video-downloader?fpr=aiagentapi) downloads supported YouTube media.
- [Video To Text](https://apify.com/truefetch/video-to-text?fpr=aiagentapi) converts supported video audio into text.
- [Best Video Downloader](https://apify.com/truefetch/best-video-downloader?fpr=aiagentapi) handles broader supported video download workflows.

These are separate Actors. YouTube Niche Listing does not invoke them automatically, and each has independent inputs, output, pricing, and coverage.

### Support and last updated

For help, contact the [TrueFetch community](https://t.me/TrueFetch) or [support](https://t.me/AiAgentApi). Provide Actor name, run ID, build number, UTC time, sanitized input, expected behavior, actual Dataset count, and the shortest useful log excerpt. Never send access tokens or unrelated personal data.

Use output in accordance with applicable law, the [YouTube Terms of Service](https://www.youtube.com/t/terms), and the [Google Privacy Policy](https://policies.google.com/privacy). Public availability does not remove copyright, privacy, contract, or communications obligations. Avoid spam, sensitive-trait profiling, engagement manipulation, and claims of identity or consent that the data does not establish.

Last updated: July 23, 2026.

# Actor input Schema

## `keyword` (type: `string`):

Required non-empty YouTube video search text. Runtime preserves the submitted text after validating that it is not whitespace-only.

## `sort_by` (type: `string`):

Required exact search ordering mode: relevance, view\_count, rating, or upload\_date. Availability and ordering follow the current YouTube search response.

## `max_results` (type: `integer`):

Required task limit from 1 to 10,000. Runtime stops collecting after this many distinct matched video IDs with channel handles; enrichment failures can produce fewer Dataset rows.

## Actor input object example

```json
{
  "keyword": "marketing",
  "sort_by": "relevance",
  "max_results": 1
}
```

# Actor output Schema

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

Open successful rows. max\_results limits matched video tasks, not guaranteed output; repeated channels are possible, missing public fields can be null or empty, and failed enrichments are skipped.

# 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 = {
    "keyword": "marketing",
    "sort_by": "relevance",
    "max_results": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("truefetch/youtube-niche-finder").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 = {
    "keyword": "marketing",
    "sort_by": "relevance",
    "max_results": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("truefetch/youtube-niche-finder").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 '{
  "keyword": "marketing",
  "sort_by": "relevance",
  "max_results": 1
}' |
apify call truefetch/youtube-niche-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=truefetch/youtube-niche-finder",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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