# YouTube Keyword Research & Topic Clusters (`tat_matrix/youtube-keyword-research`) Actor

One seed topic in; YouTube search queries grouped into video topics, ordered by demand, with the topics where small channels win. Dataset + Excel workbook. $3.50 per run, 5-15 min, free preview. No keys needed.

- **URL**: https://apify.com/tat_matrix/youtube-keyword-research.md
- **Developed by:** [Tatiana Markova](https://apify.com/tat_matrix) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.50 / full run

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/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 Keyword Research & Topic Clusters

Give it one topic. It collects what people type into YouTube search about that topic, groups the
queries into video topics, orders them by demand and marks the topics where small channels win.

- **Input:** one seed query ("sewing machine", "claude code", "razas de gatos"), a language, a country.
- **Output:** a dataset with one row per topic, and an Excel workbook with the same data laid out for reading.
- **Price:** $3.50 per full run, whatever the size of the topic. The preview is free.
- **Time:** 5 minutes for an ordinary topic, up to 15 for a large one. The preview takes under a minute.
- **No keys, no login, no proxy settings.**

Also known as a semantic core for YouTube.

### What you get

A full run on "claude code" returned 300 topics from 1,420 queries, 26 of them growth points. One row:

```json
{
  "type": "topic",
  "topic": "Claude Code Game Development",
  "main_query": "claude code game dev",
  "queries": ["claude code game design", "claude code game", "claude code game development",
              "claude code game dev", "claude code 2d game"],
  "query_count": 5,
  "demand_level": "B",
  "demand_rank": 37,
  "demand_basis": "autocomplete #1 for \"claude code g\"",
  "single_rare_query": false,
  "growth_point": true,
  "growth_type": "small_channels_win",
  "growth_reason": "2 of the first 5 videos are from channels under 50k with views at least 2x their subscribers; in the whole top 11 of 31; large channels (over 500k): 4",
  "maybe_off_topic": null,
  "videos_in_top": 31,
  "small_channel_wins": 11,
  "median_subscribers_in_top": 7640,
  "median_video_age_days": 115,
  "example_video_title": "Claude Opus 5 Took 7 Hours to Build This Game",
  "example_video_url": "https://www.youtube.com/watch?v=MsFYd8EdAXw",
  "example_video_views": 333228,
  "example_channel_subscribers": 7160
}
```

#### How to read a row

| Field | Meaning |
|---|---|
| `type` | `topic`, or `subtopic` of a large topic (then `parent_topic` is set) |
| `topic` | A short name of the topic, in the language of the market |
| `main_query` | The query of the topic with the highest demand |
| `queries` | Every query of the topic. YouTube answers them with the same videos, so one video covers them all |
| `demand_level` | `A` seen in Google Trends for YouTube search; `B` offered by autocomplete on the seed itself or in the first five on a short input; `C` offered on a short input; `D` found only by expanding another query |
| `demand_rank` | The place of the topic by demand, 1 is the strongest |
| `single_rare_query` | `true` for a topic of one level-D query: an idea, its demand is not shown |
| `growth_point` | `true` when demand is shown and the supply is weak |
| `growth_type` | `small_channels_win`: at least two of the first five videos are from channels under 50k subscribers, with 10k+ views and at least twice as many views as subscribers. `stale_top`: most of the first results are old and nothing fresh is there |
| `growth_reason` | The same in words, with the numbers of this topic |
| `maybe_off_topic` | Set when a language model found the topic to be another meaning of the seed word or nonsense. Such a topic is never a growth point |
| `example_video_*` | The strongest small-channel win of the topic: the video to look at first |

#### The workbook

`out-core.xlsx` in the key-value store of the run, in English, Spanish or Russian:

| Sheet | What is on it |
|---|---|
| How to read | The method and the thresholds of this run, in words |
| Growth points | Where a small channel can enter: the reason, the queries, the example video |
| Topics | Every topic with shown demand, strongest first |
| Tail | Topics of one rare query |
| Phrases | Every query autocomplete returned and why it is in the core or not |
| Evidence | The videos behind every topic |
| Results pages | For every query, the first ten videos as YouTube showed them, with channel, subscribers and views |
| Holes | Queries that no video answers exactly |
| Topics, all columns | Every number behind the topics |

Rows in light grey are what a language model found to have nothing to do with the subject. Nothing is
deleted: every excluded query has its reason next to it.

The same data is in `out-core.json`, `out-topics.csv`, `out-phrases.csv` and `out-evidence.csv`.

### Preview first, it is free

The default mode is `preview`. It asks YouTube autocomplete about your seed and tells you, in the status
of the run, whether the seed is a live query. Its dataset has the queries found so far.

A seed that people rarely type gives a small core, half of it padding that autocomplete glues on. For such
a seed the preview shows other wordings that people type more often, each with the same measurement.
Whether they are your topic is for you to say.

A full run checks the seed the same way and stops, free of charge, when it is weak. Tick "collect anyway"
to collect it as it is.

### Input

| Field | |
|---|---|
| `mode` | `preview` (free, default) or `full` |
| `seed` | One topic the way people search for it, 1-3 words. Required |
| `language` | `en`, `es` or `ru`. Required |
| `country` | Two-letter code, `US` by default |
| `exclude` | Words of another meaning of the seed, separated by commas |
| `workbookLanguage` | Language of the workbook: `en`, `es`, `ru`. By default the language of the market |
| `collectAnyway` | Collect a seed that turned out to be rarely typed |

### Price and when you are not charged

A full run is one charge of $3.50, made when the core is collected and before the workbook is finished.
You are not charged when:

- the mode is `preview`;
- the seed turned out weak and "collect anyway" is not ticked;
- autocomplete found nothing for the seed;
- YouTube stopped answering before the collection was complete. You still get a workbook built on what
  was collected, without topic names from the model.

The full mode runs on paid Apify plans. If you set a maximum cost for the run, set it to $4 or more: the
platform stops a run the moment its charges reach the limit. You are charged $3.50 once, never the limit.

### A long run: how to wait for it

A full run takes 5 to 15 minutes. If you start it from code or from an AI agent, do not wait for the
result in one call: start the run, then poll its status. The status message says which stage is going.
When the run has succeeded, read the dataset. A run that the platform moved to another server, or that
you resurrected after a stop, continues from where it was and is charged once.

### What it does not do

- **No search volumes.** YouTube does not publish them. Demand here is an order (A-D and a rank), not a number of searches.
- **Three languages:** English, Spanish, Russian. The rules that clean the queries are written for these.
- **One seed per run.** For several wordings of a topic, run them one by one.
- **Requests are made from servers in the United States.** The language and the topic are kept; the local
  layer of the results (videos about your own country) is weaker than from inside the country.
- **800 results pages at most.** In a very large topic the rarest queries are left without a results page
  and go into no topic; the run says how many.
- **Google Trends answers most runs, not all.** When it does not, there is no level A in that run, and the
  workbook says so.
- **It does not download videos, comments or transcripts,** and does not log in anywhere.

### How it works, briefly

1. Autocomplete: the seed and the seed with every letter, digit and question word, then one level deeper.
2. Queries with no seed words, in another language, glued on by autocomplete, or typed after one author are
   marked and left out, each with its reason.
3. The first results page for every remaining query (800 at most).
4. Official data about the videos and channels of the first ten results.
5. Two queries are one topic when their first results share at least 40% of the videos.
6. Demand from autocomplete positions and Google Trends; growth points from who wins in the first results.
7. A language model names the topics and marks what has nothing to do with the subject. It never removes
   anything, and the numbers do not depend on it.

# Actor input Schema

## `mode` (type: `string`):

Preview is free and takes under a minute: it shows whether the seed is a live YouTube query and which wordings people type more often. Full collects the whole core and builds the workbook; it runs on paid Apify plans and is charged once per run.

## `seed` (type: `string`):

One topic, typed the way people search for it on YouTube: 1-3 words. A narrow wording gives a cleaner core than a general one.

## `language` (type: `string`):

The language of the market.

## `country` (type: `string`):

Two-letter country code of the search (US, GB, MX, ES...). Requests are made from servers in the United States: the language and the topic are kept, the local layer of the results is weaker than from inside the country.

## `exclude` (type: `string`):

Optional. Words that mark another meaning of the seed, separated by commas: phrases and videos with them are kept out.

## `workbookLanguage` (type: `string`):

Headers and explanations of the workbook. Phrases and topic names stay in the language of the market. Empty: the language of the market.

## `collectAnyway` (type: `boolean`):

By default a full run stops, free of charge, when the seed turns out to be rarely typed, and shows other wordings. Tick this to collect the seed as it is.

## Actor input object example

```json
{
  "mode": "preview",
  "seed": "sewing machine",
  "language": "en",
  "country": "US",
  "collectAnyway": false
}
```

# Actor output Schema

## `topics` (type: `string`):

Full mode: one row per topic with its queries, demand level, growth point and example video. Preview mode: one row per query found by autocomplete.

## `summary` (type: `string`):

JSON: the message of the run in words, counts of queries, topics and growth points, whether the run was charged, warnings.

## `workbook` (type: `string`):

Full mode only. Excel workbook for reading: growth points, topics, tail, phrases, evidence, results pages, holes.

## `everything` (type: `string`):

Full mode only. Topics, every query with the reason it is in the core or not, and the videos behind every topic, in one JSON file.

## `queries` (type: `string`):

Full mode only. Every query autocomplete returned, its topic, its demand level and why it is in the core or not.

## `videos` (type: `string`):

Full mode only. The first results of every topic with channel, subscribers, views and age.

# 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 = {
    "mode": "preview",
    "seed": "sewing machine",
    "language": "en",
    "country": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("tat_matrix/youtube-keyword-research").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 = {
    "mode": "preview",
    "seed": "sewing machine",
    "language": "en",
    "country": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("tat_matrix/youtube-keyword-research").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 '{
  "mode": "preview",
  "seed": "sewing machine",
  "language": "en",
  "country": "US"
}' |
apify call tat_matrix/youtube-keyword-research --silent --output-dataset

```

## MCP server setup

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

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/pbHYxuxXiHDCxcai7/builds/gmZuffEerE9RNe5MZ/openapi.json