{ "openapi": "3.0.1", "info": { "title": "YouTube Search Scraper - Videos, Shorts & Channels", "description": "YouTube search scraper: videos, Shorts, channels and playlists with views, duration, publish date, channel and position. Any country and language.", "version": "1.0", "x-build-id": "3hUOpPBgQN8cicwdc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cheapapi~youtube-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cheapapi-youtube-search-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/cheapapi~youtube-search-scraper/runs": { "post": { "operationId": "runs-sync-cheapapi-youtube-search-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/cheapapi~youtube-search-scraper/run-sync": { "post": { "operationId": "run-sync-cheapapi-youtube-search-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "searchTerms": { "title": "Search terms", "type": "array", "description": "What you would type into the YouTube search box, one per line. Each search term is collected separately. Required, unless you paste YouTube search URLs in the advanced section instead.", "items": { "type": "string" } }, "maxResultsPerSearch": { "title": "Max results per search", "minimum": 10, "maximum": 700, "type": "integer", "description": "How many results (videos, Shorts, channels, playlists) to collect for every search term, in YouTube's order. You pay for results delivered; a page of 20 that delivers fewer than 8 results (e.g. no results on YouTube) adds a $0.0028 page-checked fee. Up to 700 (up to 200 with Instant processing).", "default": 20 }, "country": { "title": "Country", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "KP", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TM", "TC", "TV", "TR", "UM", "VI", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "YouTube results as seen by a viewer in this country. For a specific city or region, use the advanced location option.", "default": "US" }, "language": { "title": "Language", "enum": [ "af", "sq", "am", "ar", "hy", "az", "bn", "eu", "be", "bs", "pt-BR", "bg", "my", "ca", "ceb", "zh-CN", "zh-TW", "hr", "cs", "da", "nl", "en", "et", "pt-PT", "fil", "fi", "fr", "gl", "ka", "de", "el", "gu", "ht", "ha", "he", "hi", "hu", "is", "ig", "id", "ga", "it", "ja", "kn", "kk", "km", "rw", "ko", "ky", "lo", "lv", "lt", "mk", "ms", "ml", "mt", "mr", "mn", "ne", "no", "ps", "fa", "pl", "pt", "pa", "ro", "ru", "sr", "si", "sk", "sl", "so", "es", "es-419", "sw", "sv", "tl", "tg", "ta", "te", "th", "tr", "tk", "uk", "ur", "uz", "vi", "cy", "xh", "yo", "zu" ], "type": "string", "description": "Interface language of YouTube (affects localized titles, relative dates and ranking).", "default": "en" }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "uploadDate", "viewCount", "rating" ], "type": "string", "description": "YouTube's own sort order. YouTube sometimes ignores or reinterprets a sort option; relevance is always supported.", "default": "relevance" }, "uploadDate": { "title": "Upload date", "enum": [ "any", "lastHour", "today", "thisWeek", "thisMonth", "thisYear" ], "type": "string", "description": "Only results uploaded within this period (YouTube's upload-date filter).", "default": "any" }, "resultType": { "title": "Result type", "enum": [ "any", "video", "channel", "playlist", "movie" ], "type": "string", "description": "YouTube's type filter. Use it (rather than “Result types to keep”) when you want many results of one type, because YouTube then fills every page with that type.", "default": "any" }, "duration": { "title": "Duration", "enum": [ "any", "under4Minutes", "between4And20Minutes", "over20Minutes" ], "type": "string", "description": "YouTube's video length filter.", "default": "any" }, "features": { "title": "Features", "uniqueItems": true, "type": "array", "description": "Only results with all of these features (YouTube's feature filters).", "items": { "type": "string", "enum": [ "live", "fourK", "hd", "subtitles", "creativeCommons", "vr360", "vr180", "threeD", "hdr", "location", "purchased" ], "enumTitles": [ "Live", "4K", "HD", "Subtitles/CC", "Creative Commons", "360°", "VR180", "3D", "HDR", "Location", "Purchased" ] }, "default": [] }, "searchUrls": { "title": "YouTube search URLs", "type": "array", "description": "Instead of (or in addition to) search terms, paste YouTube search URLs such as https://www.youtube.com/results?search_query=lofi&sp=EgIQAQ%3D%3D. The search term and any filters in the URL (sp) are used; filters from the URL win over the filter options above.", "items": { "type": "string" } }, "extraUrlParameters": { "title": "Raw YouTube URL parameters", "type": "string", "description": "For experts: raw parameters added to the YouTube search URL, e.g. sp=EgIQAQ%253D%253D (the sp value URL-encoded twice). Replaces all filter options above and the filters from search URLs." }, "includeTypes": { "title": "Result types to keep", "uniqueItems": true, "type": "array", "description": "Drop result types you do not need from the output. Dropped results are not charged, but they still count towards “Max results per search” — to get many results of one type, use the “Result type” filter instead. A fetched page of 20 that keeps fewer than 8 results adds a $0.0028 page-checked fee (every 8 delivered results of a search cover one page).", "items": { "type": "string", "enum": [ "video", "short", "movie", "sponsored", "channel", "playlist", "other" ], "enumTitles": [ "Videos", "Shorts", "Movies", "Sponsored videos (ads)", "Channels", "Playlists", "Other result types" ] }, "default": [ "video", "short", "movie", "sponsored", "channel", "playlist", "other" ] }, "location": { "title": "City or region", "type": "string", "description": "Search from a specific place instead of the whole country, written as City,Region,Country, e.g. Austin,Texas,United States. Overrides Country." }, "languageName": { "title": "Language name", "type": "string", "description": "Optional full language name (e.g. Portuguese (Brazil)) for languages that are not in the Language list. Overrides Language." }, "device": { "title": "Device", "enum": [ "desktop", "mobile" ], "type": "string", "description": "Collect the results a desktop or a mobile visitor sees.", "default": "desktop" }, "operatingSystem": { "title": "Operating system", "enum": [ "auto", "windows", "macos", "android", "ios" ], "type": "string", "description": "Operating system of the simulated browser. Must match the device.", "default": "auto" }, "processingSpeed": { "title": "Processing speed", "enum": [ "auto", "standard", "fast", "instant" ], "type": "string", "description": "How quickly searches are collected. The price per result is the same at every speed.", "default": "auto" }, "maxWaitMinutes": { "title": "Maximum wait (minutes)", "minimum": 1, "maximum": 600, "type": "integer", "description": "Searches not finished after this time are reported in the run summary. They were already submitted, so each pays the page minimum ($0.0028 per requested page of 20 results, page-checked). Keep the default unless you need a hard stop.", "default": 60 }, "compareWithLastRun": { "title": "Compare with last run", "type": "boolean", "description": "Remembers which results each search returned in earlier runs and adds isNew, firstSeenAt, previousPosition and positionChange to every row. Use it with a schedule to track rankings or to pick out new videos. Every row is still delivered and priced as usual; there is no extra charge.", "default": false }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Optional. Keeps separate histories for different projects (for example \"client-a\"). Runs with the same monitor name and the same search settings are compared with each other. Letters, digits and hyphens; up to 40 characters." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }