{ "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" } } } }, "securitySchemes": { "apifyToken": { "type": "http", "scheme": "bearer", "description": "Your Apify API token (Apify Console, Settings, API and integrations)." } } }, "servers": [ { "url": "https://dataspryva--youtube-search-suggestions-scraper.apify.actor" } ], "security": [ { "apifyToken": [] } ] }