{ "data": { "id": "BfAzWaZEHHLQwq53q", "actId": "dIA3WsgJjUVXiVu24", "userId": "zq8lKbpLzTjGDayPC", "startedAt": "2026-11-10T16:19:52.402Z", "finishedAt": "2026-11-10T16:20:06.334Z", "status": "SUCCEEDED", "meta": { "origin": "CLI" }, "stats": { "durationMillis": 13847, "runTimeSecs": 13.847, "computeUnits": 0.015385555555555555, "imageSizeBytes": 319326720 }, "options": { "useCache": true, "betaPackages": false, "memoryMbytes": 4096, "diskMbytes": 8192 }, "createdByOrganizationMemberUserId": "GK9YjZRyQZVzOdoH5", "exitCode": 0, "inputSchema": "{\n \"title\": \"YouTube Search Suggestions Scraper Input\",\n \"description\": \"Collect YouTube's live search autocomplete for seed queries, with optional A-Z, question and modifier expansion.\",\n \"type\": \"object\",\n \"schemaVersion\": 1,\n \"properties\": {\n \"queries\": {\n \"title\": \"Seed queries\",\n \"type\": \"array\",\n \"description\": \"Keywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best.\",\n \"editor\": \"stringList\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"maxItems\": 1000,\n \"default\": [\n \"web scraping\"\n ],\n \"prefill\": [\n \"web scraping\"\n ]\n },\n \"mode\": {\n \"title\": \"Expansion mode\",\n \"type\": \"string\",\n \"description\": \"How far to expand each seed. Exact is one request; All runs every working expansion axis.\",\n \"editor\": \"select\",\n \"enum\": [\n \"all\",\n \"exact\",\n \"alphabet\",\n \"questions\",\n \"modifiers\",\n \"prepositions\",\n \"comparisons\",\n \"related\"\n ],\n \"enumTitles\": [\n \"All expansions\",\n \"Exact seed\",\n \"Alphabet (suffix + prefix, a-z + 0-9)\",\n \"Questions (locale-aware, prefix + suffix)\",\n \"Video modifiers (shorts, video, tutorial, ...)\",\n \"Prepositions\",\n \"Comparisons\",\n \"Related (trailing space, wildcard, review, ...)\"\n ],\n \"default\": \"exact\",\n \"prefill\": \"exact\"\n },\n \"source\": {\n \"title\": \"Suggestion source\",\n \"type\": \"string\",\n \"description\": \"YouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source.\",\n \"editor\": \"select\",\n \"enum\": [\n \"youtube\",\n \"youtubeMusic\",\n \"both\"\n ],\n \"enumTitles\": [\n \"YouTube search\",\n \"YouTube Music\",\n \"Both sources\"\n ],\n \"default\": \"youtube\",\n \"prefill\": \"youtube\"\n },\n \"language\": {\n \"title\": \"Language\",\n \"type\": \"string\",\n \"description\": \"Language used to localize suggestions.\",\n \"editor\": \"select\",\n \"enum\": [\n \"en\",\n \"es\",\n \"fr\",\n \"de\",\n \"it\",\n \"pt\",\n \"nl\",\n \"pl\",\n \"sv\",\n \"no\",\n \"da\",\n \"fi\",\n \"cs\",\n \"el\",\n \"hu\",\n \"ro\",\n \"bg\",\n \"hr\",\n \"sk\",\n \"sl\",\n \"et\",\n \"lv\",\n \"lt\",\n \"ga\",\n \"is\",\n \"mt\",\n \"ru\",\n \"uk\",\n \"be\",\n \"sr\",\n \"bs\",\n \"mk\",\n \"sq\",\n \"ar\",\n \"tr\",\n \"he\",\n \"fa\",\n \"ur\",\n \"ku\",\n \"ja\",\n \"ko\",\n \"zh-CN\",\n \"zh-TW\",\n \"hi\",\n \"bn\",\n \"ta\",\n \"te\",\n \"ml\",\n \"mr\",\n \"gu\",\n \"kn\",\n \"pa\",\n \"ne\",\n \"si\",\n \"my\",\n \"id\",\n \"th\",\n \"vi\",\n \"ms\",\n \"tl\",\n \"km\",\n \"lo\",\n \"sw\",\n \"am\",\n \"ha\",\n \"yo\",\n \"ig\",\n \"zu\",\n \"xh\",\n \"af\",\n \"az\",\n \"kk\",\n \"uz\",\n \"ky\",\n \"tg\",\n \"mn\",\n \"ka\",\n \"hy\"\n ],\n \"enumTitles\": [\n \"English\",\n \"Spanish\",\n \"French\",\n \"German\",\n \"Italian\",\n \"Portuguese\",\n \"Dutch\",\n \"Polish\",\n \"Swedish\",\n \"Norwegian\",\n \"Danish\",\n \"Finnish\",\n \"Czech\",\n \"Greek\",\n \"Hungarian\",\n \"Romanian\",\n \"Bulgarian\",\n \"Croatian\",\n \"Slovak\",\n \"Slovenian\",\n \"Estonian\",\n \"Latvian\",\n \"Lithuanian\",\n \"Irish\",\n \"Icelandic\",\n \"Maltese\",\n \"Russian\",\n \"Ukrainian\",\n \"Belarusian\",\n \"Serbian\",\n \"Bosnian\",\n \"Macedonian\",\n \"Albanian\",\n \"Arabic\",\n \"Turkish\",\n \"Hebrew\",\n \"Persian\",\n \"Urdu\",\n \"Kurdish\",\n \"Japanese\",\n \"Korean\",\n \"Chinese (Simplified)\",\n \"Chinese (Traditional)\",\n \"Hindi\",\n \"Bengali\",\n \"Tamil\",\n \"Telugu\",\n \"Malayalam\",\n \"Marathi\",\n \"Gujarati\",\n \"Kannada\",\n \"Punjabi\",\n \"Nepali\",\n \"Sinhala\",\n \"Burmese\",\n \"Indonesian\",\n \"Thai\",\n \"Vietnamese\",\n \"Malay\",\n \"Tagalog\",\n \"Khmer\",\n \"Lao\",\n \"Swahili\",\n \"Amharic\",\n \"Hausa\",\n \"Yoruba\",\n \"Igbo\",\n \"Zulu\",\n \"Xhosa\",\n \"Afrikaans\",\n \"Azerbaijani\",\n \"Kazakh\",\n \"Uzbek\",\n \"Kyrgyz\",\n \"Tajik\",\n \"Mongolian\",\n \"Georgian\",\n \"Armenian\"\n ],\n \"default\": \"en\",\n \"prefill\": \"en\"\n },\n \"market\": {\n \"title\": \"Country or region\",\n \"type\": \"string\",\n \"description\": \"Country or region used to localize suggestions.\",\n \"editor\": \"select\",\n \"enum\": [\n \"US\",\n \"GB\",\n \"CA\",\n \"AU\",\n \"NZ\",\n \"IE\",\n \"DE\",\n \"FR\",\n \"ES\",\n \"IT\",\n \"NL\",\n \"BE\",\n \"AT\",\n \"CH\",\n \"PT\",\n \"GR\",\n \"CZ\",\n \"PL\",\n \"SE\",\n \"NO\",\n \"DK\",\n \"FI\",\n \"HU\",\n \"RO\",\n \"BG\",\n \"HR\",\n \"SK\",\n \"SI\",\n \"EE\",\n \"LV\",\n \"LT\",\n \"LU\",\n \"MT\",\n \"CY\",\n \"IS\",\n \"LI\",\n \"MC\",\n \"AD\",\n \"SM\",\n \"JP\",\n \"KR\",\n \"CN\",\n \"TW\",\n \"HK\",\n \"MO\",\n \"IN\",\n \"PK\",\n \"BD\",\n \"LK\",\n \"NP\",\n \"AF\",\n \"ID\",\n \"TH\",\n \"VN\",\n \"PH\",\n \"MY\",\n \"SG\",\n \"BN\",\n \"MM\",\n \"KH\",\n \"LA\",\n \"TL\",\n \"BR\",\n \"MX\",\n \"AR\",\n \"CL\",\n \"CO\",\n \"PE\",\n \"VE\",\n \"EC\",\n \"BO\",\n \"PY\",\n \"UY\",\n \"GT\",\n \"CR\",\n \"PA\",\n \"DO\",\n \"PR\",\n \"CU\",\n \"SV\",\n \"HN\",\n \"NI\",\n \"JM\",\n \"TT\",\n \"BB\",\n \"RU\",\n \"TR\",\n \"UA\",\n \"BY\",\n \"KZ\",\n \"UZ\",\n \"AZ\",\n \"AM\",\n \"GE\",\n \"MD\",\n \"RS\",\n \"BA\",\n \"MK\",\n \"AL\",\n \"ME\",\n \"XK\",\n \"ZA\",\n \"NG\",\n \"EG\",\n \"MA\",\n \"DZ\",\n \"TN\",\n \"KE\",\n \"GH\",\n \"ET\",\n \"UG\",\n \"TZ\",\n \"RW\",\n \"ZW\",\n \"SN\",\n \"CI\",\n \"CM\",\n \"MZ\",\n \"AO\",\n \"ZM\",\n \"AE\",\n \"SA\",\n \"IL\",\n \"QA\",\n \"KW\",\n \"BH\",\n \"OM\",\n \"JO\",\n \"LB\",\n \"SY\",\n \"IQ\",\n \"IR\",\n \"YE\",\n \"PS\"\n ],\n \"enumTitles\": [\n \"United States\",\n \"United Kingdom\",\n \"Canada\",\n \"Australia\",\n \"New Zealand\",\n \"Ireland\",\n \"Germany\",\n \"France\",\n \"Spain\",\n \"Italy\",\n \"Netherlands\",\n \"Belgium\",\n \"Austria\",\n \"Switzerland\",\n \"Portugal\",\n \"Greece\",\n \"Czechia\",\n \"Poland\",\n \"Sweden\",\n \"Norway\",\n \"Denmark\",\n \"Finland\",\n \"Hungary\",\n \"Romania\",\n \"Bulgaria\",\n \"Croatia\",\n \"Slovakia\",\n \"Slovenia\",\n \"Estonia\",\n \"Latvia\",\n \"Lithuania\",\n \"Luxembourg\",\n \"Malta\",\n \"Cyprus\",\n \"Iceland\",\n \"Liechtenstein\",\n \"Monaco\",\n \"Andorra\",\n \"San Marino\",\n \"Japan\",\n \"South Korea\",\n \"China\",\n \"Taiwan\",\n \"Hong Kong\",\n \"Macao\",\n \"India\",\n \"Pakistan\",\n \"Bangladesh\",\n \"Sri Lanka\",\n \"Nepal\",\n \"Afghanistan\",\n \"Indonesia\",\n \"Thailand\",\n \"Vietnam\",\n \"Philippines\",\n \"Malaysia\",\n \"Singapore\",\n \"Brunei\",\n \"Myanmar\",\n \"Cambodia\",\n \"Laos\",\n \"Timor-Leste\",\n \"Brazil\",\n \"Mexico\",\n \"Argentina\",\n \"Chile\",\n \"Colombia\",\n \"Peru\",\n \"Venezuela\",\n \"Ecuador\",\n \"Bolivia\",\n \"Paraguay\",\n \"Uruguay\",\n \"Guatemala\",\n \"Costa Rica\",\n \"Panama\",\n \"Dominican Republic\",\n \"Puerto Rico\",\n \"Cuba\",\n \"El Salvador\",\n \"Honduras\",\n \"Nicaragua\",\n \"Jamaica\",\n \"Trinidad and Tobago\",\n \"Barbados\",\n \"Russia\",\n \"Turkey\",\n \"Ukraine\",\n \"Belarus\",\n \"Kazakhstan\",\n \"Uzbekistan\",\n \"Azerbaijan\",\n \"Armenia\",\n \"Georgia\",\n \"Moldova\",\n \"Serbia\",\n \"Bosnia and Herzegovina\",\n \"North Macedonia\",\n \"Albania\",\n \"Montenegro\",\n \"Kosovo\",\n \"South Africa\",\n \"Nigeria\",\n \"Egypt\",\n \"Morocco\",\n \"Algeria\",\n \"Tunisia\",\n \"Kenya\",\n \"Ghana\",\n \"Ethiopia\",\n \"Uganda\",\n \"Tanzania\",\n \"Rwanda\",\n \"Zimbabwe\",\n \"Senegal\",\n \"Cote d'Ivoire\",\n \"Cameroon\",\n \"Mozambique\",\n \"Angola\",\n \"Zambia\",\n \"United Arab Emirates\",\n \"Saudi Arabia\",\n \"Israel\",\n \"Qatar\",\n \"Kuwait\",\n \"Bahrain\",\n \"Oman\",\n \"Jordan\",\n \"Lebanon\",\n \"Syria\",\n \"Iraq\",\n \"Iran\",\n \"Yemen\",\n \"Palestine\"\n ],\n \"default\": \"US\",\n \"prefill\": \"US\"\n },\n \"maxItems\": {\n \"title\": \"Maximum rows\",\n \"type\": \"integer\",\n \"description\": \"Global cap on suggestion rows across all seeds and sources.\",\n \"minimum\": 1,\n \"maximum\": 50000,\n \"default\": 5000,\n \"prefill\": 3\n },\n \"maxSuggestionsPerSeed\": {\n \"title\": \"Maximum suggestions per seed\",\n \"type\": \"integer\",\n \"description\": \"Cap on rows kept for each seed after the expansion plan runs.\",\n \"minimum\": 1,\n \"maximum\": 10000,\n \"default\": 2000,\n \"prefill\": 3\n },\n \"maxQueriesPerSeed\": {\n \"title\": \"Maximum queries per seed\",\n \"type\": \"integer\",\n \"description\": \"Cap on autocomplete requests per seed and source. Exact stays one request.\",\n \"minimum\": 1,\n \"maximum\": 1000,\n \"default\": 300,\n \"prefill\": 300\n },\n \"expansionDepth\": {\n \"title\": \"Recursion depth\",\n \"type\": \"integer\",\n \"description\": \"0 = selected mode only. 1-2 re-query the best suggestions for deeper long-tail coverage.\",\n \"minimum\": 0,\n \"maximum\": 2,\n \"default\": 0,\n \"prefill\": 0\n },\n \"dedupeAcrossSeeds\": {\n \"title\": \"Remove duplicates across seeds\",\n \"type\": \"boolean\",\n \"description\": \"Keep one row when the same suggestion appears for more than one seed. Per-seed duplicates are always removed.\",\n \"default\": false,\n \"prefill\": false\n },\n \"minLength\": {\n \"title\": \"Minimum length\",\n \"type\": \"integer\",\n \"description\": \"Drop suggestions shorter than this many characters.\",\n \"minimum\": 1,\n \"maximum\": 200\n },\n \"maxLength\": {\n \"title\": \"Maximum length\",\n \"type\": \"integer\",\n \"description\": \"Drop suggestions longer than this many characters.\",\n \"minimum\": 1,\n \"maximum\": 500\n },\n \"containsKeyword\": {\n \"title\": \"Contains keyword\",\n \"type\": \"string\",\n \"description\": \"Keep suggestions containing this text. Prefix with ! to exclude it instead.\",\n \"editor\": \"textfield\"\n },\n \"excludeTerms\": {\n \"title\": \"Exclude terms\",\n \"type\": \"array\",\n \"description\": \"Drop suggestions containing any of these terms.\",\n \"editor\": \"stringList\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": [],\n \"prefill\": []\n },\n \"minWordCount\": {\n \"title\": \"Minimum word count\",\n \"type\": \"integer\",\n \"description\": \"Drop suggestions with fewer words than this.\",\n \"minimum\": 0,\n \"maximum\": 20,\n \"default\": 0,\n \"prefill\": 0\n },\n \"onlyQuestions\": {\n \"title\": \"Only questions\",\n \"type\": \"boolean\",\n \"description\": \"Keep only suggestions that look like questions.\",\n \"default\": false,\n \"prefill\": false\n },\n \"mustContainSeed\": {\n \"title\": \"Must contain seed\",\n \"type\": \"boolean\",\n \"description\": \"Keep only suggestions that contain the seed keyword.\",\n \"default\": false,\n \"prefill\": false\n },\n \"includeEntityCards\": {\n \"title\": \"Include channel and topic cards\",\n \"type\": \"boolean\",\n \"description\": \"Keep channel and topic suggestions, with their entity metadata, when YouTube returns them.\",\n \"default\": true,\n \"prefill\": true\n },\n \"includeSearchUrl\": {\n \"title\": \"Include search links\",\n \"type\": \"boolean\",\n \"description\": \"Add a ready-to-open YouTube or YouTube Music search URL to every row.\",\n \"default\": true,\n \"prefill\": true\n }\n },\n \"required\": [\n \"queries\"\n ]\n}", "readme": "# YouTube Search Suggestions Scraper\n\nDiscover 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.\n\nNo 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.\n\n## What this actor does\n\n- **Live YouTube suggestions:** each exact seed query returns up to 14 suggestions, the same list the signed-out YouTube search box shows.\n- **Eight expansion modes:** `exact`, `alphabet` (suffix and prefix, letters and digits), `questions`, `modifiers`, `prepositions`, `comparisons`, `related`, and `all` (the union).\n- **Optional recursion:** re-query the best suggestions to depth 1 or 2 for deeper long-tail coverage.\n- **Locale targeting:** 134 countries and 78 languages, with localized question and modifier words for 19 languages.\n- **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.\n- **Filters and caps:** length, word count, question-only, contains-seed, exclude terms, per-seed and global row caps.\n- **Per-seed deduplication:** repeated phrases are merged with a best rank and an appearance count. Optional cross-seed deduplication.\n- **Empty fields are omitted:** records only contain values that are actually populated.\n\n## Output per suggestion\n\n| Field | Description |\n|---|---|\n| `recordType` | `suggestion` for a suggestion row, `status` when a seed produced nothing. |\n| `id` | Stable 16-character ID for the source, seed, suggestion and locale. |\n| `suggestion` | The exact phrase YouTube autocomplete returned. |\n| `seed` | The seed query that produced this row. |\n| `inputQuery` | Alias of `seed`, kept for older integrations. |\n| `query` | The exact expansion query that produced the best rank. |\n| `type` | `suggestion`, `alphabet`, `question`, `modifier`, `preposition`, `comparison`, `related` or `recursive`. |\n| `rank` | Best 1-based position across every query that returned the phrase. |\n| `appearances` | Number of expansion queries that returned the phrase. |\n| `depth` | 0 for the base plan, 1-2 for recursion. |\n| `parentQuery` | The query that led to a recursive row. |\n| `language`, `market`, `locale` | Requested language, country and combined locale. |\n| `source` | `youtube` or `youtubeMusic`. |\n| `suggestionType` | `query`, `channel` or `topic`. |\n| `subTypes` | YouTube's raw numeric suggestion codes, when present. |\n| `entityId`, `entityName`, `entityDescription` | Channel/topic card identity, name and description or handle. |\n| `entityImageUrl`, `entityUrl` | Card image and source-provided entity link, when present. |\n| `channelId`, `channelHandle`, `channelUrl` | Channel card details, when present. |\n| `wordCount`, `isQuestion`, `containsSeed` | Derived text signals. |\n| `searchUrl` | Ready-to-open YouTube or YouTube Music search URL. |\n| `scrapedAt` | ISO-8601 UTC timestamp. |\n\nWhen 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.\n\n## Input\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `queries` | array | `[\"web scraping\"]` | Seed keywords or phrases. 1-3 word seeds work best. |\n| `mode` | string | `exact` | `all`, `exact`, `alphabet`, `questions`, `modifiers`, `prepositions`, `comparisons` or `related`. |\n| `source` | string | `youtube` | `youtube`, `youtubeMusic` or `both`. |\n| `language` | string | `en` | Language code used to localize suggestions. |\n| `market` | string | `US` | Country or region code used to localize suggestions. |\n| `maxItems` | integer | `5000` | Global cap on suggestion rows. |\n| `maxSuggestionsPerSeed` | integer | `2000` | Rows kept per seed after the expansion plan. |\n| `maxQueriesPerSeed` | integer | `300` | Autocomplete requests per seed and source. |\n| `expansionDepth` | integer | `0` | `0` = selected mode only; `1`-`2` = re-query the best suggestions. |\n| `dedupeAcrossSeeds` | boolean | `false` | Keep one row when a phrase appears for several seeds. Per-seed dedupe is always on. |\n| `minLength` | integer | – | Drop shorter suggestions. |\n| `maxLength` | integer | – | Drop longer suggestions. |\n| `containsKeyword` | string | – | Keep suggestions containing this text; prefix with `!` to exclude it. |\n| `excludeTerms` | array | `[]` | Drop suggestions containing any of these terms. |\n| `minWordCount` | integer | `0` | Drop suggestions with fewer words. |\n| `onlyQuestions` | boolean | `false` | Keep only question-shaped suggestions. |\n| `mustContainSeed` | boolean | `false` | Keep only suggestions that contain the seed. |\n| `includeEntityCards` | boolean | `true` | Keep channel/topic cards and their metadata. |\n| `includeSearchUrl` | boolean | `true` | Add a ready-to-open search URL to every row. |\n\nOld tasks that use `keywords`, `maxSuggestions`, `deduplicateSuggestions` or `country` keep working; those legacy keys are mapped to the new fields automatically.\n\n## Examples\n\n### Example: exact suggestions for one seed\n\n```json\n{\n \"queries\": [\"web scraping\"],\n \"mode\": \"exact\",\n \"language\": \"en\",\n \"market\": \"US\",\n \"maxItems\": 20\n}\n```\n\n### Example: full keyword expansion\n\n```json\n{\n \"queries\": [\"coffee\", \"minecraft\"],\n \"mode\": \"all\",\n \"expansionDepth\": 1,\n \"maxItems\": 5000\n}\n```\n\n### Example: Spanish questions with channel cards\n\n```json\n{\n \"queries\": [\"café\"],\n \"mode\": \"questions\",\n \"language\": \"es\",\n \"market\": \"ES\",\n \"includeEntityCards\": true\n}\n```\n\n### Example: YouTube Music suggestions\n\n```json\n{\n \"queries\": [\"lofi hip hop\"],\n \"source\": \"youtubeMusic\",\n \"mode\": \"exact\",\n \"maxItems\": 20\n}\n```\n\n### Example: long-tail ideas that mention the seed\n\n```json\n{\n \"queries\": [\"running shoes\"],\n \"mode\": \"all\",\n \"mustContainSeed\": true,\n \"minWordCount\": 3,\n \"maxItems\": 1000\n}\n```\n\n## Use cases\n\n- **YouTube SEO and content planning** — turn one topic into the phrases viewers actually type.\n- **Keyword research** — compare suggestions across markets and languages.\n- **Title and script ideas** — collect question and long-tail variants for a niche.\n- **Creator discovery** — surface channel cards YouTube attaches to short brand seeds.\n- **Trend monitoring** — schedule a run and diff `suggestion` or `rank` between snapshots.\n- **YouTube Music research** — read the separate music-biased suggestion list for artists, genres and moods.\n\n## FAQ\n\n### Does this require a YouTube account, API key or cookies?\n\nNo. It reads YouTube's public search-box suggestions and works signed out.\n\n### How many suggestions does one query return?\n\nYouTube returns up to 14 suggestions per query. There is no pagination and no parameter that raises that ceiling.\n\n### Why are some suggestions missing or different?\n\nAutocomplete 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.\n\n### Can I get search volume or competition metrics?\n\nNo. YouTube autocomplete does not publish search volume, CPC or difficulty. Those numbers come from separate paid keyword or search-results products.\n\n### Why does a long seed return nothing?\n\nAutocomplete 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.\n\n### What are channel and topic cards?\n\nSome 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.\n\n### How does deduplication work?\n\nDuplicate 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.\n\n### What is the YouTube Music source?\n\nYouTube 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.\n\n### Does this support YouTube TV suggestions?\n\nNo. YouTube TV does not expose a separate public suggestion list; it uses the same search suggestions as YouTube.\n\n### Do I need to set up a proxy?\n\nNo. The actor chooses a working connection to YouTube automatically. Just fill in the input and run it.\n\n---\n\nThis 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.\n\n## Use it as an API (server mode)\n\nNeed one answer right away instead of a batch job? Send the input as an HTTP request and the results come back in the response. There's no run to start and poll.\n\n```bash\ncurl -H \"Authorization: Bearer $APIFY_TOKEN\" \\\n \"https://dataspryva--youtube-search-suggestions-scraper.apify.actor/?queries=web%20scraping&maxItems=10\"\n```\n\nOr POST the same input as JSON:\n\n```bash\ncurl -X POST -H \"Authorization: Bearer $APIFY_TOKEN\" -H \"Content-Type: application/json\" \\\n -d '{\"queries\": [\"web scraping\"], \"maxItems\": 10}' \\\n \"https://dataspryva--youtube-search-suggestions-scraper.apify.actor/\"\n```\n\n- The fields are the same as in the input above. With GET, repeat a parameter once for each value in a list.\n- You get back a JSON array with the same records a normal run saves. They're saved to the run's dataset too.\n- Each request is capped at 100 results and 4 minutes. For bigger jobs, start a normal run.\n- The request runs in your own Apify account at the Actor's normal price (a start fee plus a price per result). The server shuts down after a minute with no requests.\n- The Server tab on this page lists every parameter and lets you try a request from your browser.\n", "actorDefinition": { "actorSpecification": 1, "name": "youtube-search-suggestions-scraper", "title": "YouTube Search Suggestions Scraper", "description": "Collect YouTube's live search autocomplete for any seed, with A-Z, question and modifier keyword expansion, locale targeting, rank, channel/topic cards and deduplicated JSON rows.", "version": "1.0", "buildTag": "latest", "dockerfile": "./Dockerfile", "readme": "# YouTube Search Suggestions Scraper\n\nDiscover 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.\n\nNo 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.\n\n## What this actor does\n\n- **Live YouTube suggestions:** each exact seed query returns up to 14 suggestions, the same list the signed-out YouTube search box shows.\n- **Eight expansion modes:** `exact`, `alphabet` (suffix and prefix, letters and digits), `questions`, `modifiers`, `prepositions`, `comparisons`, `related`, and `all` (the union).\n- **Optional recursion:** re-query the best suggestions to depth 1 or 2 for deeper long-tail coverage.\n- **Locale targeting:** 134 countries and 78 languages, with localized question and modifier words for 19 languages.\n- **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.\n- **Filters and caps:** length, word count, question-only, contains-seed, exclude terms, per-seed and global row caps.\n- **Per-seed deduplication:** repeated phrases are merged with a best rank and an appearance count. Optional cross-seed deduplication.\n- **Empty fields are omitted:** records only contain values that are actually populated.\n\n## Output per suggestion\n\n| Field | Description |\n|---|---|\n| `recordType` | `suggestion` for a suggestion row, `status` when a seed produced nothing. |\n| `id` | Stable 16-character ID for the source, seed, suggestion and locale. |\n| `suggestion` | The exact phrase YouTube autocomplete returned. |\n| `seed` | The seed query that produced this row. |\n| `inputQuery` | Alias of `seed`, kept for older integrations. |\n| `query` | The exact expansion query that produced the best rank. |\n| `type` | `suggestion`, `alphabet`, `question`, `modifier`, `preposition`, `comparison`, `related` or `recursive`. |\n| `rank` | Best 1-based position across every query that returned the phrase. |\n| `appearances` | Number of expansion queries that returned the phrase. |\n| `depth` | 0 for the base plan, 1-2 for recursion. |\n| `parentQuery` | The query that led to a recursive row. |\n| `language`, `market`, `locale` | Requested language, country and combined locale. |\n| `source` | `youtube` or `youtubeMusic`. |\n| `suggestionType` | `query`, `channel` or `topic`. |\n| `subTypes` | YouTube's raw numeric suggestion codes, when present. |\n| `entityId`, `entityName`, `entityDescription` | Channel/topic card identity, name and description or handle. |\n| `entityImageUrl`, `entityUrl` | Card image and source-provided entity link, when present. |\n| `channelId`, `channelHandle`, `channelUrl` | Channel card details, when present. |\n| `wordCount`, `isQuestion`, `containsSeed` | Derived text signals. |\n| `searchUrl` | Ready-to-open YouTube or YouTube Music search URL. |\n| `scrapedAt` | ISO-8601 UTC timestamp. |\n\nWhen 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.\n\n## Input\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `queries` | array | `[\"web scraping\"]` | Seed keywords or phrases. 1-3 word seeds work best. |\n| `mode` | string | `exact` | `all`, `exact`, `alphabet`, `questions`, `modifiers`, `prepositions`, `comparisons` or `related`. |\n| `source` | string | `youtube` | `youtube`, `youtubeMusic` or `both`. |\n| `language` | string | `en` | Language code used to localize suggestions. |\n| `market` | string | `US` | Country or region code used to localize suggestions. |\n| `maxItems` | integer | `5000` | Global cap on suggestion rows. |\n| `maxSuggestionsPerSeed` | integer | `2000` | Rows kept per seed after the expansion plan. |\n| `maxQueriesPerSeed` | integer | `300` | Autocomplete requests per seed and source. |\n| `expansionDepth` | integer | `0` | `0` = selected mode only; `1`-`2` = re-query the best suggestions. |\n| `dedupeAcrossSeeds` | boolean | `false` | Keep one row when a phrase appears for several seeds. Per-seed dedupe is always on. |\n| `minLength` | integer | – | Drop shorter suggestions. |\n| `maxLength` | integer | – | Drop longer suggestions. |\n| `containsKeyword` | string | – | Keep suggestions containing this text; prefix with `!` to exclude it. |\n| `excludeTerms` | array | `[]` | Drop suggestions containing any of these terms. |\n| `minWordCount` | integer | `0` | Drop suggestions with fewer words. |\n| `onlyQuestions` | boolean | `false` | Keep only question-shaped suggestions. |\n| `mustContainSeed` | boolean | `false` | Keep only suggestions that contain the seed. |\n| `includeEntityCards` | boolean | `true` | Keep channel/topic cards and their metadata. |\n| `includeSearchUrl` | boolean | `true` | Add a ready-to-open search URL to every row. |\n\nOld tasks that use `keywords`, `maxSuggestions`, `deduplicateSuggestions` or `country` keep working; those legacy keys are mapped to the new fields automatically.\n\n## Examples\n\n### Example: exact suggestions for one seed\n\n```json\n{\n \"queries\": [\"web scraping\"],\n \"mode\": \"exact\",\n \"language\": \"en\",\n \"market\": \"US\",\n \"maxItems\": 20\n}\n```\n\n### Example: full keyword expansion\n\n```json\n{\n \"queries\": [\"coffee\", \"minecraft\"],\n \"mode\": \"all\",\n \"expansionDepth\": 1,\n \"maxItems\": 5000\n}\n```\n\n### Example: Spanish questions with channel cards\n\n```json\n{\n \"queries\": [\"café\"],\n \"mode\": \"questions\",\n \"language\": \"es\",\n \"market\": \"ES\",\n \"includeEntityCards\": true\n}\n```\n\n### Example: YouTube Music suggestions\n\n```json\n{\n \"queries\": [\"lofi hip hop\"],\n \"source\": \"youtubeMusic\",\n \"mode\": \"exact\",\n \"maxItems\": 20\n}\n```\n\n### Example: long-tail ideas that mention the seed\n\n```json\n{\n \"queries\": [\"running shoes\"],\n \"mode\": \"all\",\n \"mustContainSeed\": true,\n \"minWordCount\": 3,\n \"maxItems\": 1000\n}\n```\n\n## Use cases\n\n- **YouTube SEO and content planning** — turn one topic into the phrases viewers actually type.\n- **Keyword research** — compare suggestions across markets and languages.\n- **Title and script ideas** — collect question and long-tail variants for a niche.\n- **Creator discovery** — surface channel cards YouTube attaches to short brand seeds.\n- **Trend monitoring** — schedule a run and diff `suggestion` or `rank` between snapshots.\n- **YouTube Music research** — read the separate music-biased suggestion list for artists, genres and moods.\n\n## FAQ\n\n### Does this require a YouTube account, API key or cookies?\n\nNo. It reads YouTube's public search-box suggestions and works signed out.\n\n### How many suggestions does one query return?\n\nYouTube returns up to 14 suggestions per query. There is no pagination and no parameter that raises that ceiling.\n\n### Why are some suggestions missing or different?\n\nAutocomplete 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.\n\n### Can I get search volume or competition metrics?\n\nNo. YouTube autocomplete does not publish search volume, CPC or difficulty. Those numbers come from separate paid keyword or search-results products.\n\n### Why does a long seed return nothing?\n\nAutocomplete 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.\n\n### What are channel and topic cards?\n\nSome 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.\n\n### How does deduplication work?\n\nDuplicate 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.\n\n### What is the YouTube Music source?\n\nYouTube 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.\n\n### Does this support YouTube TV suggestions?\n\nNo. YouTube TV does not expose a separate public suggestion list; it uses the same search suggestions as YouTube.\n\n### Do I need to set up a proxy?\n\nNo. The actor chooses a working connection to YouTube automatically. Just fill in the input and run it.\n\n---\n\nThis 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.\n\n## Use it as an API (server mode)\n\nNeed one answer right away instead of a batch job? Send the input as an HTTP request and the results come back in the response. There's no run to start and poll.\n\n```bash\ncurl -H \"Authorization: Bearer $APIFY_TOKEN\" \\\n \"https://dataspryva--youtube-search-suggestions-scraper.apify.actor/?queries=web%20scraping&maxItems=10\"\n```\n\nOr POST the same input as JSON:\n\n```bash\ncurl -X POST -H \"Authorization: Bearer $APIFY_TOKEN\" -H \"Content-Type: application/json\" \\\n -d '{\"queries\": [\"web scraping\"], \"maxItems\": 10}' \\\n \"https://dataspryva--youtube-search-suggestions-scraper.apify.actor/\"\n```\n\n- The fields are the same as in the input above. With GET, repeat a parameter once for each value in a list.\n- You get back a JSON array with the same records a normal run saves. They're saved to the run's dataset too.\n- Each request is capped at 100 results and 4 minutes. For bigger jobs, start a normal run.\n- The request runs in your own Apify account at the Actor's normal price (a start fee plus a price per result). The server shuts down after a minute with no requests.\n- The Server tab on this page lists every parameter and lets you try a request from your browser.\n", "input": { "title": "YouTube Search Suggestions Scraper Input", "description": "Collect YouTube's live search autocomplete for seed queries, with optional A-Z, question and modifier expansion.", "type": "object", "schemaVersion": 1, "properties": { "queries": { "title": "Seed queries", "type": "array", "description": "Keywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best.", "editor": "stringList", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000, "default": [ "web scraping" ], "prefill": [ "web scraping" ] }, "mode": { "title": "Expansion mode", "type": "string", "description": "How far to expand each seed. Exact is one request; All runs every working expansion axis.", "editor": "select", "enum": [ "all", "exact", "alphabet", "questions", "modifiers", "prepositions", "comparisons", "related" ], "enumTitles": [ "All expansions", "Exact seed", "Alphabet (suffix + prefix, a-z + 0-9)", "Questions (locale-aware, prefix + suffix)", "Video modifiers (shorts, video, tutorial, ...)", "Prepositions", "Comparisons", "Related (trailing space, wildcard, review, ...)" ], "default": "exact", "prefill": "exact" }, "source": { "title": "Suggestion source", "type": "string", "description": "YouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source.", "editor": "select", "enum": [ "youtube", "youtubeMusic", "both" ], "enumTitles": [ "YouTube search", "YouTube Music", "Both sources" ], "default": "youtube", "prefill": "youtube" }, "language": { "title": "Language", "type": "string", "description": "Language used to localize suggestions.", "editor": "select", "enum": [ "en", "es", "fr", "de", "it", "pt", "nl", "pl", "sv", "no", "da", "fi", "cs", "el", "hu", "ro", "bg", "hr", "sk", "sl", "et", "lv", "lt", "ga", "is", "mt", "ru", "uk", "be", "sr", "bs", "mk", "sq", "ar", "tr", "he", "fa", "ur", "ku", "ja", "ko", "zh-CN", "zh-TW", "hi", "bn", "ta", "te", "ml", "mr", "gu", "kn", "pa", "ne", "si", "my", "id", "th", "vi", "ms", "tl", "km", "lo", "sw", "am", "ha", "yo", "ig", "zu", "xh", "af", "az", "kk", "uz", "ky", "tg", "mn", "ka", "hy" ], "enumTitles": [ "English", "Spanish", "French", "German", "Italian", "Portuguese", "Dutch", "Polish", "Swedish", "Norwegian", "Danish", "Finnish", "Czech", "Greek", "Hungarian", "Romanian", "Bulgarian", "Croatian", "Slovak", "Slovenian", "Estonian", "Latvian", "Lithuanian", "Irish", "Icelandic", "Maltese", "Russian", "Ukrainian", "Belarusian", "Serbian", "Bosnian", "Macedonian", "Albanian", "Arabic", "Turkish", "Hebrew", "Persian", "Urdu", "Kurdish", "Japanese", "Korean", "Chinese (Simplified)", "Chinese (Traditional)", "Hindi", "Bengali", "Tamil", "Telugu", "Malayalam", "Marathi", "Gujarati", "Kannada", "Punjabi", "Nepali", "Sinhala", "Burmese", "Indonesian", "Thai", "Vietnamese", "Malay", "Tagalog", "Khmer", "Lao", "Swahili", "Amharic", "Hausa", "Yoruba", "Igbo", "Zulu", "Xhosa", "Afrikaans", "Azerbaijani", "Kazakh", "Uzbek", "Kyrgyz", "Tajik", "Mongolian", "Georgian", "Armenian" ], "default": "en", "prefill": "en" }, "market": { "title": "Country or region", "type": "string", "description": "Country or region used to localize suggestions.", "editor": "select", "enum": [ "US", "GB", "CA", "AU", "NZ", "IE", "DE", "FR", "ES", "IT", "NL", "BE", "AT", "CH", "PT", "GR", "CZ", "PL", "SE", "NO", "DK", "FI", "HU", "RO", "BG", "HR", "SK", "SI", "EE", "LV", "LT", "LU", "MT", "CY", "IS", "LI", "MC", "AD", "SM", "JP", "KR", "CN", "TW", "HK", "MO", "IN", "PK", "BD", "LK", "NP", "AF", "ID", "TH", "VN", "PH", "MY", "SG", "BN", "MM", "KH", "LA", "TL", "BR", "MX", "AR", "CL", "CO", "PE", "VE", "EC", "BO", "PY", "UY", "GT", "CR", "PA", "DO", "PR", "CU", "SV", "HN", "NI", "JM", "TT", "BB", "RU", "TR", "UA", "BY", "KZ", "UZ", "AZ", "AM", "GE", "MD", "RS", "BA", "MK", "AL", "ME", "XK", "ZA", "NG", "EG", "MA", "DZ", "TN", "KE", "GH", "ET", "UG", "TZ", "RW", "ZW", "SN", "CI", "CM", "MZ", "AO", "ZM", "AE", "SA", "IL", "QA", "KW", "BH", "OM", "JO", "LB", "SY", "IQ", "IR", "YE", "PS" ], "enumTitles": [ "United States", "United Kingdom", "Canada", "Australia", "New Zealand", "Ireland", "Germany", "France", "Spain", "Italy", "Netherlands", "Belgium", "Austria", "Switzerland", "Portugal", "Greece", "Czechia", "Poland", "Sweden", "Norway", "Denmark", "Finland", "Hungary", "Romania", "Bulgaria", "Croatia", "Slovakia", "Slovenia", "Estonia", "Latvia", "Lithuania", "Luxembourg", "Malta", "Cyprus", "Iceland", "Liechtenstein", "Monaco", "Andorra", "San Marino", "Japan", "South Korea", "China", "Taiwan", "Hong Kong", "Macao", "India", "Pakistan", "Bangladesh", "Sri Lanka", "Nepal", "Afghanistan", "Indonesia", "Thailand", "Vietnam", "Philippines", "Malaysia", "Singapore", "Brunei", "Myanmar", "Cambodia", "Laos", "Timor-Leste", "Brazil", "Mexico", "Argentina", "Chile", "Colombia", "Peru", "Venezuela", "Ecuador", "Bolivia", "Paraguay", "Uruguay", "Guatemala", "Costa Rica", "Panama", "Dominican Republic", "Puerto Rico", "Cuba", "El Salvador", "Honduras", "Nicaragua", "Jamaica", "Trinidad and Tobago", "Barbados", "Russia", "Turkey", "Ukraine", "Belarus", "Kazakhstan", "Uzbekistan", "Azerbaijan", "Armenia", "Georgia", "Moldova", "Serbia", "Bosnia and Herzegovina", "North Macedonia", "Albania", "Montenegro", "Kosovo", "South Africa", "Nigeria", "Egypt", "Morocco", "Algeria", "Tunisia", "Kenya", "Ghana", "Ethiopia", "Uganda", "Tanzania", "Rwanda", "Zimbabwe", "Senegal", "Cote d'Ivoire", "Cameroon", "Mozambique", "Angola", "Zambia", "United Arab Emirates", "Saudi Arabia", "Israel", "Qatar", "Kuwait", "Bahrain", "Oman", "Jordan", "Lebanon", "Syria", "Iraq", "Iran", "Yemen", "Palestine" ], "default": "US", "prefill": "US" }, "maxItems": { "title": "Maximum rows", "type": "integer", "description": "Global cap on suggestion rows across all seeds and sources.", "minimum": 1, "maximum": 50000, "default": 5000, "prefill": 3 }, "maxSuggestionsPerSeed": { "title": "Maximum suggestions per seed", "type": "integer", "description": "Cap on rows kept for each seed after the expansion plan runs.", "minimum": 1, "maximum": 10000, "default": 2000, "prefill": 3 }, "maxQueriesPerSeed": { "title": "Maximum queries per seed", "type": "integer", "description": "Cap on autocomplete requests per seed and source. Exact stays one request.", "minimum": 1, "maximum": 1000, "default": 300, "prefill": 300 }, "expansionDepth": { "title": "Recursion depth", "type": "integer", "description": "0 = selected mode only. 1-2 re-query the best suggestions for deeper long-tail coverage.", "minimum": 0, "maximum": 2, "default": 0, "prefill": 0 }, "dedupeAcrossSeeds": { "title": "Remove duplicates across seeds", "type": "boolean", "description": "Keep one row when the same suggestion appears for more than one seed. Per-seed duplicates are always removed.", "default": false, "prefill": false }, "minLength": { "title": "Minimum length", "type": "integer", "description": "Drop suggestions shorter than this many characters.", "minimum": 1, "maximum": 200 }, "maxLength": { "title": "Maximum length", "type": "integer", "description": "Drop suggestions longer than this many characters.", "minimum": 1, "maximum": 500 }, "containsKeyword": { "title": "Contains keyword", "type": "string", "description": "Keep suggestions containing this text. Prefix with ! to exclude it instead.", "editor": "textfield" }, "excludeTerms": { "title": "Exclude terms", "type": "array", "description": "Drop suggestions containing any of these terms.", "editor": "stringList", "items": { "type": "string" }, "default": [], "prefill": [] }, "minWordCount": { "title": "Minimum word count", "type": "integer", "description": "Drop suggestions with fewer words than this.", "minimum": 0, "maximum": 20, "default": 0, "prefill": 0 }, "onlyQuestions": { "title": "Only questions", "type": "boolean", "description": "Keep only suggestions that look like questions.", "default": false, "prefill": false }, "mustContainSeed": { "title": "Must contain seed", "type": "boolean", "description": "Keep only suggestions that contain the seed keyword.", "default": false, "prefill": false }, "includeEntityCards": { "title": "Include channel and topic cards", "type": "boolean", "description": "Keep channel and topic suggestions, with their entity metadata, when YouTube returns them.", "default": true, "prefill": true }, "includeSearchUrl": { "title": "Include search links", "type": "boolean", "description": "Add a ready-to-open YouTube or YouTube Music search URL to every row.", "default": true, "prefill": true } }, "required": [ "queries" ] }, "output": { "actorOutputSchemaVersion": 1, "title": "YouTube Search Suggestions Scraper Output", "description": "Autocomplete suggestion rows with seed, expansion type, rank, locale, source, search URL and channel/topic metadata when available.", "properties": { "suggestions": { "type": "string", "title": "YouTube suggestions", "description": "Dataset containing all scraped YouTube autocomplete suggestion rows.", "template": "{{links.apiDefaultDatasetUrl}}/items" } } }, "defaultRunOptions": { "build": "latest", "timeoutSecs": 900, "memoryMbytes": 1024 }, "storages": { "dataset": { "actorSpecification": 1, "views": { "overview": { "title": "YouTube suggestions", "transformation": { "fields": [ "suggestion", "seed", "type", "rank", "locale", "source", "suggestionType", "searchUrl" ] }, "display": { "component": "table", "properties": {} } } } } }, "environmentVariables": {}, "webServerSchema": { "openapi": "3.0.3", "info": { "title": "YouTube Search Suggestions Scraper (server mode)", "version": "1.1", "description": "Send one lookup and get the results back in the response. It takes the same input as a normal run: query parameters with GET, or a JSON body with POST. At most 100 results and 240 seconds per request; start a normal run for bigger jobs. Requests run in your own Apify account at the Actor's normal price.", "x-oa-server-mode": "1.1" }, "paths": { "/": { "get": { "operationId": "lookupGet", "summary": "Run one lookup (query parameters)", "parameters": [ { "name": "queries", "in": "query", "required": true, "description": "Keywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best. (GET: repeat the parameter once per value.)", "schema": { "type": "array", "default": [ "web scraping" ], "minItems": 1, "maxItems": 3, "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "web scraping" ] }, { "name": "mode", "in": "query", "required": false, "description": "How far to expand each seed. Exact is one request; All runs every working expansion axis.", "schema": { "type": "string", "enum": [ "all", "exact", "alphabet", "questions", "modifiers", "prepositions", "comparisons", "related" ], "default": "exact" } }, { "name": "source", "in": "query", "required": false, "description": "YouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source.", "schema": { "type": "string", "enum": [ "youtube", "youtubeMusic", "both" ], "default": "youtube" } }, { "name": "language", "in": "query", "required": false, "description": "Language used to localize suggestions.", "schema": { "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt", "nl", "pl", "sv", "no", "da", "fi", "cs", "el", "hu", "ro", "bg", "hr", "sk", "sl", "et", "lv", "lt", "ga", "is", "mt", "ru", "uk", "be", "sr", "bs", "mk", "sq", "ar", "tr", "he", "fa", "ur", "ku", "ja", "ko", "zh-CN", "zh-TW", "hi", "bn", "ta", "te", "ml", "mr", "gu", "kn", "pa", "ne", "si", "my", "id", "th", "vi", "ms", "tl", "km", "lo", "sw", "am", "ha", "yo", "ig", "zu", "xh", "af", "az", "kk", "uz", "ky", "tg", "mn", "ka", "hy" ], "default": "en" } }, { "name": "market", "in": "query", "required": false, "description": "Country or region used to localize suggestions.", "schema": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "NZ", "IE", "DE", "FR", "ES", "IT", "NL", "BE", "AT", "CH", "PT", "GR", "CZ", "PL", "SE", "NO", "DK", "FI", "HU", "RO", "BG", "HR", "SK", "SI", "EE", "LV", "LT", "LU", "MT", "CY", "IS", "LI", "MC", "AD", "SM", "JP", "KR", "CN", "TW", "HK", "MO", "IN", "PK", "BD", "LK", "NP", "AF", "ID", "TH", "VN", "PH", "MY", "SG", "BN", "MM", "KH", "LA", "TL", "BR", "MX", "AR", "CL", "CO", "PE", "VE", "EC", "BO", "PY", "UY", "GT", "CR", "PA", "DO", "PR", "CU", "SV", "HN", "NI", "JM", "TT", "BB", "RU", "TR", "UA", "BY", "KZ", "UZ", "AZ", "AM", "GE", "MD", "RS", "BA", "MK", "AL", "ME", "XK", "ZA", "NG", "EG", "MA", "DZ", "TN", "KE", "GH", "ET", "UG", "TZ", "RW", "ZW", "SN", "CI", "CM", "MZ", "AO", "ZM", "AE", "SA", "IL", "QA", "KW", "BH", "OM", "JO", "LB", "SY", "IQ", "IR", "YE", "PS" ], "default": "US" } }, { "name": "maxItems", "in": "query", "required": false, "description": "Global cap on suggestion rows across all seeds and sources.", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100 }, "example": 10 }, { "name": "maxSuggestionsPerSeed", "in": "query", "required": false, "description": "Cap on rows kept for each seed after the expansion plan runs.", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100 } }, { "name": "maxQueriesPerSeed", "in": "query", "required": false, "description": "Cap on autocomplete requests per seed and source. Exact stays one request.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 50 } }, { "name": "expansionDepth", "in": "query", "required": false, "description": "0 = selected mode only. 1-2 re-query the best suggestions for deeper long-tail coverage.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 2 } }, { "name": "dedupeAcrossSeeds", "in": "query", "required": false, "description": "Keep one row when the same suggestion appears for more than one seed. Per-seed duplicates are always removed.", "schema": { "type": "boolean", "default": false } }, { "name": "minLength", "in": "query", "required": false, "description": "Drop suggestions shorter than this many characters.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "maxLength", "in": "query", "required": false, "description": "Drop suggestions longer than this many characters.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "containsKeyword", "in": "query", "required": false, "description": "Keep suggestions containing this text. Prefix with ! to exclude it instead.", "schema": { "type": "string" } }, { "name": "excludeTerms", "in": "query", "required": false, "description": "Drop suggestions containing any of these terms. (GET: repeat the parameter once per value.)", "schema": { "type": "array", "default": [], "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "minWordCount", "in": "query", "required": false, "description": "Drop suggestions with fewer words than this.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 20 } }, { "name": "onlyQuestions", "in": "query", "required": false, "description": "Keep only suggestions that look like questions.", "schema": { "type": "boolean", "default": false } }, { "name": "mustContainSeed", "in": "query", "required": false, "description": "Keep only suggestions that contain the seed keyword.", "schema": { "type": "boolean", "default": false } }, { "name": "includeEntityCards", "in": "query", "required": false, "description": "Keep channel and topic suggestions, with their entity metadata, when YouTube returns them.", "schema": { "type": "boolean", "default": true } }, { "name": "includeSearchUrl", "in": "query", "required": false, "description": "Add a ready-to-open YouTube or YouTube Music search URL to every row.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "The results as a JSON array (at most 100). They are also saved to the run's dataset and billed per result, like a normal run.", "headers": { "X-Item-Count": { "schema": { "type": "integer" }, "description": "Results returned." }, "X-Status-Message": { "schema": { "type": "string" }, "description": "The Actor's last status message, e.g. why nothing was found." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "example": [ { "recordType": "suggestion", "id": "f46c5b88d2e925b4", "suggestion": "web scraping weather data python", "seed": "web scraping", "inputQuery": "web scraping", "query": "web scraping", "type": "suggestion", "rank": 1, "appearances": 1, "depth": 0, "language": "en", "market": "US", "locale": "en-US", "source": "youtube", "suggestionType": "query", "subTypes": [ 512 ], "wordCount": 5, "isQuestion": false, "containsSeed": true, "searchUrl": "https://www.youtube.com/results?search_query=web+scraping+weather+data+python&hl=en&gl=US", "scrapedAt": "2026-11-10T15:34:55.281951+00:00" } ] } } }, "400": { "description": "Invalid, missing or unknown input fields. Nothing ran.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_input", "errorDescription": "queries: required" } } } }, "422": { "description": "The Actor could not complete this request (for example, nothing matches). No results were delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The request used up its 240 s budget. The results found so far are in partialItems.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "partialItems": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ] } } } } } }, "post": { "operationId": "lookupPost", "summary": "Run one lookup (JSON body)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "queries": { "type": "array", "default": [ "web scraping" ], "minItems": 1, "maxItems": 3, "items": { "type": "string" }, "description": "Keywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best." }, "mode": { "type": "string", "enum": [ "all", "exact", "alphabet", "questions", "modifiers", "prepositions", "comparisons", "related" ], "default": "exact", "description": "How far to expand each seed. Exact is one request; All runs every working expansion axis." }, "source": { "type": "string", "enum": [ "youtube", "youtubeMusic", "both" ], "default": "youtube", "description": "YouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source." }, "language": { "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt", "nl", "pl", "sv", "no", "da", "fi", "cs", "el", "hu", "ro", "bg", "hr", "sk", "sl", "et", "lv", "lt", "ga", "is", "mt", "ru", "uk", "be", "sr", "bs", "mk", "sq", "ar", "tr", "he", "fa", "ur", "ku", "ja", "ko", "zh-CN", "zh-TW", "hi", "bn", "ta", "te", "ml", "mr", "gu", "kn", "pa", "ne", "si", "my", "id", "th", "vi", "ms", "tl", "km", "lo", "sw", "am", "ha", "yo", "ig", "zu", "xh", "af", "az", "kk", "uz", "ky", "tg", "mn", "ka", "hy" ], "default": "en", "description": "Language used to localize suggestions." }, "market": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "NZ", "IE", "DE", "FR", "ES", "IT", "NL", "BE", "AT", "CH", "PT", "GR", "CZ", "PL", "SE", "NO", "DK", "FI", "HU", "RO", "BG", "HR", "SK", "SI", "EE", "LV", "LT", "LU", "MT", "CY", "IS", "LI", "MC", "AD", "SM", "JP", "KR", "CN", "TW", "HK", "MO", "IN", "PK", "BD", "LK", "NP", "AF", "ID", "TH", "VN", "PH", "MY", "SG", "BN", "MM", "KH", "LA", "TL", "BR", "MX", "AR", "CL", "CO", "PE", "VE", "EC", "BO", "PY", "UY", "GT", "CR", "PA", "DO", "PR", "CU", "SV", "HN", "NI", "JM", "TT", "BB", "RU", "TR", "UA", "BY", "KZ", "UZ", "AZ", "AM", "GE", "MD", "RS", "BA", "MK", "AL", "ME", "XK", "ZA", "NG", "EG", "MA", "DZ", "TN", "KE", "GH", "ET", "UG", "TZ", "RW", "ZW", "SN", "CI", "CM", "MZ", "AO", "ZM", "AE", "SA", "IL", "QA", "KW", "BH", "OM", "JO", "LB", "SY", "IQ", "IR", "YE", "PS" ], "default": "US", "description": "Country or region used to localize suggestions." }, "maxItems": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100, "description": "Global cap on suggestion rows across all seeds and sources." }, "maxSuggestionsPerSeed": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100, "description": "Cap on rows kept for each seed after the expansion plan runs." }, "maxQueriesPerSeed": { "type": "integer", "default": 50, "minimum": 1, "maximum": 50, "description": "Cap on autocomplete requests per seed and source. Exact stays one request." }, "expansionDepth": { "type": "integer", "default": 0, "minimum": 0, "maximum": 2, "description": "0 = selected mode only. 1-2 re-query the best suggestions for deeper long-tail coverage." }, "dedupeAcrossSeeds": { "type": "boolean", "default": false, "description": "Keep one row when the same suggestion appears for more than one seed. Per-seed duplicates are always removed." }, "minLength": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Drop suggestions shorter than this many characters." }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Drop suggestions longer than this many characters." }, "containsKeyword": { "type": "string", "description": "Keep suggestions containing this text. Prefix with ! to exclude it instead." }, "excludeTerms": { "type": "array", "default": [], "items": { "type": "string" }, "description": "Drop suggestions containing any of these terms." }, "minWordCount": { "type": "integer", "default": 0, "minimum": 0, "maximum": 20, "description": "Drop suggestions with fewer words than this." }, "onlyQuestions": { "type": "boolean", "default": false, "description": "Keep only suggestions that look like questions." }, "mustContainSeed": { "type": "boolean", "default": false, "description": "Keep only suggestions that contain the seed keyword." }, "includeEntityCards": { "type": "boolean", "default": true, "description": "Keep channel and topic suggestions, with their entity metadata, when YouTube returns them." }, "includeSearchUrl": { "type": "boolean", "default": true, "description": "Add a ready-to-open YouTube or YouTube Music search URL to every row." } }, "additionalProperties": false, "required": [ "queries" ] }, "example": { "queries": [ "web scraping" ], "maxItems": 10 } } } }, "responses": { "200": { "description": "The results as a JSON array (at most 100). They are also saved to the run's dataset and billed per result, like a normal run.", "headers": { "X-Item-Count": { "schema": { "type": "integer" }, "description": "Results returned." }, "X-Status-Message": { "schema": { "type": "string" }, "description": "The Actor's last status message, e.g. why nothing was found." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "example": [ { "recordType": "suggestion", "id": "f46c5b88d2e925b4", "suggestion": "web scraping weather data python", "seed": "web scraping", "inputQuery": "web scraping", "query": "web scraping", "type": "suggestion", "rank": 1, "appearances": 1, "depth": 0, "language": "en", "market": "US", "locale": "en-US", "source": "youtube", "suggestionType": "query", "subTypes": [ 512 ], "wordCount": 5, "isQuestion": false, "containsSeed": true, "searchUrl": "https://www.youtube.com/results?search_query=web+scraping+weather+data+python&hl=en&gl=US", "scrapedAt": "2026-11-10T15:34:55.281951+00:00" } ] } } }, "400": { "description": "Invalid, missing or unknown input fields. Nothing ran.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_input", "errorDescription": "queries: required" } } } }, "422": { "description": "The Actor could not complete this request (for example, nothing matches). No results were delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The request used up its 240 s budget. The results found so far are in partialItems.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "partialItems": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ] } } } } } } } }, "components": { "schemas": { "Item": { "type": "object", "description": "One result, the same record a normal run saves to its dataset.", "properties": { "recordType": { "type": "string" }, "id": { "type": "string" }, "suggestion": { "type": "string" }, "seed": { "type": "string" }, "inputQuery": { "type": "string" }, "query": { "type": "string" }, "type": { "type": "string" }, "rank": { "type": "integer" }, "appearances": { "type": "integer" }, "depth": { "type": "integer" }, "language": { "type": "string" }, "market": { "type": "string" }, "locale": { "type": "string" }, "source": { "type": "string" }, "suggestionType": { "type": "string" }, "subTypes": { "type": "array", "items": { "type": "integer" } }, "wordCount": { "type": "integer" }, "isQuestion": { "type": "boolean" }, "containsSeed": { "type": "boolean" }, "searchUrl": { "type": "string" }, "scrapedAt": { "type": "string" } }, "example": { "recordType": "suggestion", "id": "f46c5b88d2e925b4", "suggestion": "web scraping weather data python", "seed": "web scraping", "inputQuery": "web scraping", "query": "web scraping", "type": "suggestion", "rank": 1, "appearances": 1, "depth": 0, "language": "en", "market": "US", "locale": "en-US", "source": "youtube", "suggestionType": "query", "subTypes": [ 512 ], "wordCount": 5, "isQuestion": false, "containsSeed": true, "searchUrl": "https://www.youtube.com/results?search_query=web+scraping+weather+data+python&hl=en&gl=US", "scrapedAt": "2026-11-10T15:34:55.281951+00:00" } }, "Error": { "type": "object", "required": [ "error", "errorDescription" ], "properties": { "error": { "type": "string", "enum": [ "invalid_input", "request_failed", "internal_error", "timeout", "busy", "not_found", "method_not_allowed", "payload_too_large" ] }, "errorDescription": { "type": "string" } } } } } } }, "buildNumber": "1.0.3", "imageDigest": "01da57ccfaf2e71a8ce2be10efbebfb1de6f52350230dafd472cb4be48600a64", "actVersion": { "sourceType": "SOURCE_FILES", "buildTag": "latest", "versionNumber": "1.0" }, "usage": { "ACTOR_COMPUTE_UNITS": 0.015385555555555555 } } }