Use YouTube Search Suggestions Scraper with Python

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

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

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

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`queries`	array	required	Keywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best.
`mode`	string	optional	How far to expand each seed. Exact is one request; All runs every working expansion axis.
`source`	string	optional	YouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source.
`language`	string	optional	Language used to localize suggestions.
`market`	string	optional	Country or region used to localize suggestions.
`maxItems`	integer	optional	Global cap on suggestion rows across all seeds and sources.
`maxSuggestionsPerSeed`	integer	optional	Cap on rows kept for each seed after the expansion plan runs.
`maxQueriesPerSeed`	integer	optional	Cap on autocomplete requests per seed and source. Exact stays one request.
`expansionDepth`	integer	optional	0 = selected mode only. 1-2 re-query the best suggestions for deeper long-tail coverage.
`dedupeAcrossSeeds`	boolean	optional	Keep one row when the same suggestion appears for more than one seed. Per-seed duplicates are always removed.
`minLength`	integer	optional	Drop suggestions shorter than this many characters.
`maxLength`	integer	optional	Drop suggestions longer than this many characters.
`containsKeyword`	string	optional	Keep suggestions containing this text. Prefix with ! to exclude it instead.
`excludeTerms`	array	optional	Drop suggestions containing any of these terms.
`minWordCount`	integer	optional	Drop suggestions with fewer words than this.
`onlyQuestions`	boolean	optional	Keep only suggestions that look like questions.
`mustContainSeed`	boolean	optional	Keep only suggestions that contain the seed keyword.
`includeEntityCards`	boolean	optional	Keep channel and topic suggestions, with their entity metadata, when YouTube returns them.
`includeSearchUrl`	boolean	optional	Add a ready-to-open YouTube or YouTube Music search URL to every row.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/dIA3WsgJjUVXiVu24/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

Autocomplete suggestion rows with seed, expansion type, rank, locale, source, search URL and channel/topic metadata when available.

Questions before you run

Which inputs are required?

The published required fields are queries

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build Fuf8WidkcEKo6eqVe and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.