# YouTube Search Suggestions Scraper (`dataspryva/youtube-search-suggestions-scraper`) Actor

Get public YouTube autocomplete suggestions for keyword research, content discovery, and SEO planning.

- **URL**: https://apify.com/dataspryva/youtube-search-suggestions-scraper.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** SEO tools, Social media, Videos
- **Security:** Limited permissions
- **Stats:** 1 total users, 1 monthly users, 92.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 Search Suggestions Scraper

Discover the phrases YouTube puts in its search box. Enter one or more seed queries and collect the platform's live autocomplete suggestions as clean, ranked JSON or CSV rows — with optional alphabet, question, modifier and related-search expansion for keyword research, video planning and audience research.

No YouTube account, API key, cookies or user-supplied proxy is needed. The actor reads YouTube's public autocomplete response and chooses a working connection automatically.

### What this actor does

- **Live YouTube suggestions:** each exact seed query returns up to 14 suggestions, the same list the signed-out YouTube search box shows.
- **Eight expansion modes:** `exact`, `alphabet` (suffix and prefix, letters and digits), `questions`, `modifiers`, `prepositions`, `comparisons`, `related`, and `all` (the union).
- **Optional recursion:** re-query the best suggestions to depth 1 or 2 for deeper long-tail coverage.
- **Locale targeting:** 134 countries and 78 languages, with localized question and modifier words for 19 languages.
- **Channel/topic cards:** when YouTube attaches a creator or topic card to a suggestion, its name, description or handle, image, channel ID and entity URL are included when supplied.
- **Filters and caps:** length, word count, question-only, contains-seed, exclude terms, per-seed and global row caps.
- **Per-seed deduplication:** repeated phrases are merged with a best rank and an appearance count. Optional cross-seed deduplication.
- **Empty fields are omitted:** records only contain values that are actually populated.

### Output per suggestion

| Field | Description |
|---|---|
| `recordType` | `suggestion` for a suggestion row, `status` when a seed produced nothing. |
| `id` | Stable 16-character ID for the source, seed, suggestion and locale. |
| `suggestion` | The exact phrase YouTube autocomplete returned. |
| `seed` | The seed query that produced this row. |
| `inputQuery` | Alias of `seed`, kept for older integrations. |
| `query` | The exact expansion query that produced the best rank. |
| `type` | `suggestion`, `alphabet`, `question`, `modifier`, `preposition`, `comparison`, `related` or `recursive`. |
| `rank` | Best 1-based position across every query that returned the phrase. |
| `appearances` | Number of expansion queries that returned the phrase. |
| `depth` | 0 for the base plan, 1-2 for recursion. |
| `parentQuery` | The query that led to a recursive row. |
| `language`, `market`, `locale` | Requested language, country and combined locale. |
| `source` | `youtube` or `youtubeMusic`. |
| `suggestionType` | `query`, `channel` or `topic`. |
| `subTypes` | YouTube's raw numeric suggestion codes, when present. |
| `entityId`, `entityName`, `entityDescription` | Channel/topic card identity, name and description or handle. |
| `entityImageUrl`, `entityUrl` | Card image and source-provided entity link, when present. |
| `channelId`, `channelHandle`, `channelUrl` | Channel card details, when present. |
| `wordCount`, `isQuestion`, `containsSeed` | Derived text signals. |
| `searchUrl` | Ready-to-open YouTube or YouTube Music search URL. |
| `scrapedAt` | ISO-8601 UTC timestamp. |

When a seed returns no rows, the actor emits one status row instead: `recordType` (`status`), `status`, `seed`, `query`, `language`, `market`, `source` and `suggestionCount` (`0`). Status values are `no_suggestions`, `suggestions_unavailable`, `invalid_query` and `blocked`. An unavailable YouTube Music response is reported as `suggestions_unavailable` for the seed.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `queries` | array | `["web scraping"]` | Seed keywords or phrases. 1-3 word seeds work best. |
| `mode` | string | `exact` | `all`, `exact`, `alphabet`, `questions`, `modifiers`, `prepositions`, `comparisons` or `related`. |
| `source` | string | `youtube` | `youtube`, `youtubeMusic` or `both`. |
| `language` | string | `en` | Language code used to localize suggestions. |
| `market` | string | `US` | Country or region code used to localize suggestions. |
| `maxItems` | integer | `5000` | Global cap on suggestion rows. |
| `maxSuggestionsPerSeed` | integer | `2000` | Rows kept per seed after the expansion plan. |
| `maxQueriesPerSeed` | integer | `300` | Autocomplete requests per seed and source. |
| `expansionDepth` | integer | `0` | `0` = selected mode only; `1`-`2` = re-query the best suggestions. |
| `dedupeAcrossSeeds` | boolean | `false` | Keep one row when a phrase appears for several seeds. Per-seed dedupe is always on. |
| `minLength` | integer | – | Drop shorter suggestions. |
| `maxLength` | integer | – | Drop longer suggestions. |
| `containsKeyword` | string | – | Keep suggestions containing this text; prefix with `!` to exclude it. |
| `excludeTerms` | array | `[]` | Drop suggestions containing any of these terms. |
| `minWordCount` | integer | `0` | Drop suggestions with fewer words. |
| `onlyQuestions` | boolean | `false` | Keep only question-shaped suggestions. |
| `mustContainSeed` | boolean | `false` | Keep only suggestions that contain the seed. |
| `includeEntityCards` | boolean | `true` | Keep channel/topic cards and their metadata. |
| `includeSearchUrl` | boolean | `true` | Add a ready-to-open search URL to every row. |

Old tasks that use `keywords`, `maxSuggestions`, `deduplicateSuggestions` or `country` keep working; those legacy keys are mapped to the new fields automatically.

### Examples

#### Example: exact suggestions for one seed

```json
{
  "queries": ["web scraping"],
  "mode": "exact",
  "language": "en",
  "market": "US",
  "maxItems": 20
}
```

#### Example: full keyword expansion

```json
{
  "queries": ["coffee", "minecraft"],
  "mode": "all",
  "expansionDepth": 1,
  "maxItems": 5000
}
```

#### Example: Spanish questions with channel cards

```json
{
  "queries": ["café"],
  "mode": "questions",
  "language": "es",
  "market": "ES",
  "includeEntityCards": true
}
```

#### Example: YouTube Music suggestions

```json
{
  "queries": ["lofi hip hop"],
  "source": "youtubeMusic",
  "mode": "exact",
  "maxItems": 20
}
```

#### Example: long-tail ideas that mention the seed

```json
{
  "queries": ["running shoes"],
  "mode": "all",
  "mustContainSeed": true,
  "minWordCount": 3,
  "maxItems": 1000
}
```

### Use cases

- **YouTube SEO and content planning** — turn one topic into the phrases viewers actually type.
- **Keyword research** — compare suggestions across markets and languages.
- **Title and script ideas** — collect question and long-tail variants for a niche.
- **Creator discovery** — surface channel cards YouTube attaches to short brand seeds.
- **Trend monitoring** — schedule a run and diff `suggestion` or `rank` between snapshots.
- **YouTube Music research** — read the separate music-biased suggestion list for artists, genres and moods.

### FAQ

#### Does this require a YouTube account, API key or cookies?

No. It reads YouTube's public search-box suggestions and works signed out.

#### How many suggestions does one query return?

YouTube returns up to 14 suggestions per query. There is no pagination and no parameter that raises that ceiling.

#### Why are some suggestions missing or different?

Autocomplete is personalized by language, country, current trends and the request location, and YouTube can change it at any time. The actor records the requested locale but cannot guarantee a specific list.

#### Can I get search volume or competition metrics?

No. YouTube autocomplete does not publish search volume, CPC or difficulty. Those numbers come from separate paid keyword or search-results products.

#### Why does a long seed return nothing?

Autocomplete completes prefixes, so four- and five-word seeds often return few or no suggestions. Use a 1-3 word seed, or use `alphabet` mode to expand around a long seed.

#### What are channel and topic cards?

Some suggestions carry a creator or topic card with a name, handle, image, channel ID or entity link. The actor includes those fields when YouTube supplies them. Set `includeEntityCards` to `false` if you only want plain query suggestions.

#### How does deduplication work?

Duplicate phrases inside one seed are merged into one row with the best `rank` and an `appearances` count. Cross-seed duplicates are kept by default so each seed's list stays complete; set `dedupeAcrossSeeds` to `true` for one row per phrase across the whole run.

#### What is the YouTube Music source?

YouTube Music has its own music-biased suggestion list. It typically returns 6-10 suggestions per query and can return none for some seeds or locales; it is not a replacement for the main YouTube search box. Use `source: "youtubeMusic"` for music research or `both` to collect both lists.

#### Does this support YouTube TV suggestions?

No. YouTube TV does not expose a separate public suggestion list; it uses the same search suggestions as YouTube.

#### Do I need to set up a proxy?

No. The actor chooses a working connection to YouTube automatically. Just fill in the input and run it.

***

This is a third-party actor that reads publicly available YouTube autocomplete data. It is not affiliated with, endorsed by or sponsored by YouTube or Google.

# Actor input Schema

## `queries` (type: `array`):

Keywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best.

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

How far to expand each seed. Exact is one request; All runs every working expansion axis.

## `source` (type: `string`):

YouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source.

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

Language used to localize suggestions.

## `market` (type: `string`):

Country or region used to localize suggestions.

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

Global cap on suggestion rows across all seeds and sources.

## `maxSuggestionsPerSeed` (type: `integer`):

Cap on rows kept for each seed after the expansion plan runs.

## `maxQueriesPerSeed` (type: `integer`):

Cap on autocomplete requests per seed and source. Exact stays one request.

## `expansionDepth` (type: `integer`):

0 = selected mode only. 1-2 re-query the best suggestions for deeper long-tail coverage.

## `dedupeAcrossSeeds` (type: `boolean`):

Keep one row when the same suggestion appears for more than one seed. Per-seed duplicates are always removed.

## `minLength` (type: `integer`):

Drop suggestions shorter than this many characters.

## `maxLength` (type: `integer`):

Drop suggestions longer than this many characters.

## `containsKeyword` (type: `string`):

Keep suggestions containing this text. Prefix with ! to exclude it instead.

## `excludeTerms` (type: `array`):

Drop suggestions containing any of these terms.

## `minWordCount` (type: `integer`):

Drop suggestions with fewer words than this.

## `onlyQuestions` (type: `boolean`):

Keep only suggestions that look like questions.

## `mustContainSeed` (type: `boolean`):

Keep only suggestions that contain the seed keyword.

## `includeEntityCards` (type: `boolean`):

Keep channel and topic suggestions, with their entity metadata, when YouTube returns them.

## `includeSearchUrl` (type: `boolean`):

Add a ready-to-open YouTube or YouTube Music search URL to every row.

## Actor input object example

```json
{
  "queries": [
    "web scraping"
  ],
  "mode": "exact",
  "source": "youtube",
  "language": "en",
  "market": "US",
  "maxItems": 3,
  "maxSuggestionsPerSeed": 3,
  "maxQueriesPerSeed": 300,
  "expansionDepth": 0,
  "dedupeAcrossSeeds": false,
  "excludeTerms": [],
  "minWordCount": 0,
  "onlyQuestions": false,
  "mustContainSeed": false,
  "includeEntityCards": true,
  "includeSearchUrl": true
}
```

# Actor output Schema

## `suggestions` (type: `string`):

Dataset containing all scraped YouTube autocomplete suggestion rows.

# 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 = {
    "queries": [
        "web scraping"
    ],
    "mode": "exact",
    "source": "youtube",
    "language": "en",
    "market": "US",
    "maxItems": 3,
    "maxSuggestionsPerSeed": 3,
    "maxQueriesPerSeed": 300,
    "expansionDepth": 0,
    "dedupeAcrossSeeds": false,
    "excludeTerms": [],
    "minWordCount": 0,
    "onlyQuestions": false,
    "mustContainSeed": false,
    "includeEntityCards": true,
    "includeSearchUrl": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/youtube-search-suggestions-scraper").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 = {
    "queries": ["web scraping"],
    "mode": "exact",
    "source": "youtube",
    "language": "en",
    "market": "US",
    "maxItems": 3,
    "maxSuggestionsPerSeed": 3,
    "maxQueriesPerSeed": 300,
    "expansionDepth": 0,
    "dedupeAcrossSeeds": False,
    "excludeTerms": [],
    "minWordCount": 0,
    "onlyQuestions": False,
    "mustContainSeed": False,
    "includeEntityCards": True,
    "includeSearchUrl": True,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/youtube-search-suggestions-scraper").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 '{
  "queries": [
    "web scraping"
  ],
  "mode": "exact",
  "source": "youtube",
  "language": "en",
  "market": "US",
  "maxItems": 3,
  "maxSuggestionsPerSeed": 3,
  "maxQueriesPerSeed": 300,
  "expansionDepth": 0,
  "dedupeAcrossSeeds": false,
  "excludeTerms": [],
  "minWordCount": 0,
  "onlyQuestions": false,
  "mustContainSeed": false,
  "includeEntityCards": true,
  "includeSearchUrl": true
}' |
apify call dataspryva/youtube-search-suggestions-scraper --silent --output-dataset

```

## MCP server setup

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

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/dIA3WsgJjUVXiVu24/builds/Fuf8WidkcEKo6eqVe/openapi.json