View raw JSON
{
"type": "object",
"required": [],
"properties": {
"body": {
"type": "object",
"title": "Input schema for the youtube-search-scraper actor",
"required": [],
"properties": {
"is3D": {
"type": "boolean",
"title": "3D",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s 3D feature filter for keyword searches. It does not convert video; false, null or omission does not request an inverse filter."
},
"is4K": {
"type": "boolean",
"title": "4K",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s 4K feature filter for keyword searches. This is a search tag, not independent resolution verification or conversion. False, null or omission does not request an inverse filter."
},
"isHD": {
"type": "boolean",
"title": "HD",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s HD feature filter for keyword searches. It does not verify or convert image resolution; false, null or omission does not request an inverse filter.",
"groupCaption": "Features",
"groupDescription": "What you could select under the Features section of the Filtering&Sorting menu on Youtube"
},
"hasCC": {
"type": "boolean",
"title": "Creative Commons",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests the Creative Commons licensing-tag filter for keyword searches. It neither fetches subtitles nor independently verifies reuse rights. False, null or omission does not request an inverse filter."
},
"is360": {
"type": "boolean",
"title": "360 degrees",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s 360-degree feature filter for keyword searches. It does not convert or play the media; false, null or omission does not request an inverse filter."
},
"isHDR": {
"type": "boolean",
"title": "HDR",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s HDR feature filter for keyword searches. It does not independently verify or convert the media; false, null or omission does not request an inverse filter."
},
"isLive": {
"type": "boolean",
"title": "Live",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s Live feature filter for keyword searches. Set the separate stream limit for stream collection; this flag does not open playback. False, null or omission does not request an inverse filter."
},
"isVR180": {
"type": "boolean",
"title": "VR180",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s VR180 feature filter for keyword searches. It does not convert or play the media; false, null or omission does not request an inverse filter."
},
"isBought": {
"type": "boolean",
"title": "Purchased",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s Purchased feature filter for keyword searches. It does not purchase content or grant access to restricted videos. False, null or omission does not request an inverse filter."
},
"startUrls": {
"type": "array",
"title": "Direct URLs",
"editor": "requestListSources",
"default": [],
"example": [
{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
],
"description": "Optional list of video, channel, playlist, hashtag or search-results URLs, with entries such as {url: \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"}. Default is an empty list. Providing URLs causes searchQueries to be ignored, and keyword search filters do not apply. Video-type separation can vary across URL collections; these URLs do not promise a complete inventory.",
"sectionCaption": "🔗 Direct URLs"
},
"videoType": {
"enum": [
"video",
"movie"
],
"type": "string",
"title": "Video type filter",
"editor": "select",
"example": "video",
"nullable": true,
"enumTitles": [
"Video",
"Film"
],
"description": "Optional keyword-search filter: video or movie. Omit or use null to leave this filter unset. It does not control direct-URL collection or download media."
},
"dateFilter": {
"enum": [
"hour",
"today",
"week",
"month",
"year"
],
"type": "string",
"title": "Date filter",
"editor": "select",
"example": "month",
"nullable": true,
"enumTitles": [
"Last hour",
"Today",
"This week",
"This month",
"This year"
],
"description": "Optional keyword-search upload-date filter: hour (last hour), today, week (this week), month (this month) or year (this year). It does not control direct URLs; exact calendar and timezone boundaries are not specified."
},
"maxResults": {
"type": "integer",
"unit": "Videos",
"title": "Maximum videos per search term",
"default": 0,
"example": 10,
"maximum": 999999,
"minimum": 0,
"prefill": 10,
"description": "Optional integer from 0 to 999999, default 0. Sets the ordinary-video cap per keyword; zero excludes ordinary videos from that search. It also limits regular videos for channel collection. The prefilled 10 is an example, not the default. This is not a whole-run record cap or an exact returned count."
},
"hasLocation": {
"type": "boolean",
"title": "Location",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s Location feature filter for keyword searches. It does not choose a country or verify the creator’s physical location. False, null or omission does not request an inverse filter."
},
"hasSubtitles": {
"type": "boolean",
"title": "Subtitles/CC",
"editor": "checkbox",
"nullable": true,
"description": "Optional. True requests YouTube’s Subtitles/CC feature filter for keyword searches. Actual subtitle retrieval uses the separate transcriptionAndSubtitle setting. False, null or omission does not request an inverse filter."
},
"lengthFilter": {
"enum": [
"under4",
"between420",
"plus20"
],
"type": "string",
"title": "Length filter",
"editor": "select",
"example": "between420",
"nullable": true,
"enumTitles": [
"Under 4 minutes",
"4-20 minutes",
"Over 20 minutes"
],
"description": "Optional keyword-search filter: under4 (under 4 minutes), between420 (4–20 minutes) or plus20 (over 20 minutes). It does not control direct URLs. Exact inclusion at category boundaries is not specified."
},
"sortVideosBy": {
"enum": [
"NEWEST",
"POPULAR",
"OLDEST"
],
"type": "string",
"title": "Sort by",
"editor": "select",
"example": "NEWEST",
"enumTitles": [
"Newest",
"Popular",
"Oldest"
],
"description": "Optional channel-page order: NEWEST, POPULAR or OLDEST, corresponding to the channel’s Videos, Shorts and Live sorting buttons. No default is set. This differs from keyword-search sortingOrder; setting oldestPostDate resets channel order to NEWEST."
},
"sortingOrder": {
"enum": [
"relevance",
"rating",
"date",
"views"
],
"type": "string",
"title": "Sorting order",
"editor": "select",
"example": "relevance",
"nullable": true,
"enumTitles": [
"Relevance",
"Rating",
"Upload date",
"View count"
],
"description": "Optional keyword-search order: relevance, rating, date (upload date) or views (view count). Omit or use null to leave it unset. It does not reorder direct-URL collections. YouTube filters can mix Shorts with ordinary videos.",
"sectionCaption": "✅ Add filters",
"sectionDescription": "Specify the parameters you want to sort/filter videos by. They will be applied as if you manually did so on Youtube's search page. Only works if you provide search term, not for the direct URLs.\n \n ⚠️ Using YouTube filters may mix Shorts with regular videos. This is a limitation on YouTube's side. We recommend checking it manually."
},
"saveSubsToKVS": {
"type": "boolean",
"title": "Save subtitles to key-value store",
"editor": "hidden",
"example": false,
"description": "Optional. True also saves fetched subtitles to the supplier’s key-value storage. Generated speech-to-text transcripts are stored there regardless of this flag. Storage references do not deliver local files or guarantee access to the complete text."
},
"searchQueries": {
"type": "array",
"title": "Search terms",
"editor": "stringList",
"example": [
"web scraping tutorials"
],
"prefill": [
"Crawlee"
],
"nullable": false,
"description": "Optional list of terms as entered in YouTube search. The prefilled Crawlee term is an example, not a default. Set the desired video-type caps for the query; all three default to zero. If startUrls are supplied, these terms are ignored."
},
"aiVideoSummary": {
"type": "boolean",
"title": "Add-on: AI video summary ($)",
"default": false,
"example": false,
"description": "Optional paid addition, default false. When enabled, AI may generate a concise conceptual summary using visual and audio content. Use only an actually returned summary and label it as AI-generated; it is not independently verified content or a verbatim transcript."
},
"oldestPostDate": {
"type": "string",
"title": "Scrape videos published after [date]",
"editor": "datepicker",
"example": "2024-01-01",
"pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])(T[0-2]\\d:[0-5]\\d(:[0-5]\\d)?(\\.\\d+)?Z?)?$|^(\\d+)\\s*(minute|hour|day|week|month|year)s?$",
"dateType": "absoluteOrRelative",
"description": "Optional channel-URL filter requesting videos uploaded on or after an absolute date or within a relative age range, such as 2024-01-01 or 2 days. The source describes 1 day as today and 2 days as yesterday plus today. Enabling it resets channel order to NEWEST and may add cost. It does not apply to other URL routes or keyword searches; no universal timezone or exact timestamp-edge guarantee is specified.",
"sectionCaption": "📅 Date range (applicable only to scraping by channels URL) ($)"
},
"subtitlesFormat": {
"enum": [
"srt",
"vtt",
"xml",
"plaintext"
],
"type": "string",
"title": "Subtitle format",
"editor": "select",
"default": "srt",
"example": "srt",
"enumTitles": [
"SRT",
"WEBVTT",
"XML",
"plaintext"
],
"description": "Optional, default srt. Choose srt, vtt, xml or plaintext for fetched subtitles. A subtitle-retrieval mode must be active. The selection does not promise a downloadable file or determine generated speech-to-text output format."
},
"maxResultStreams": {
"type": "integer",
"unit": "Videos",
"title": "Maximum streams per search term",
"default": 0,
"example": 0,
"maximum": 999999,
"minimum": 0,
"prefill": 0,
"description": "Optional integer from 0 to 999999, default 0. Sets the stream-video cap per keyword; zero excludes streams from that search. It is separate from the ordinary-video and Shorts caps, not a whole-run limit or a guarantee of that many records."
},
"maxResultsShorts": {
"type": "integer",
"unit": "Videos",
"title": "Maximum shorts per search term",
"default": 0,
"example": 5,
"maximum": 999999,
"minimum": 0,
"prefill": 0,
"description": "Optional integer from 0 to 999999, default 0. Sets the Shorts cap per keyword; zero excludes Shorts from that search. It is separate from ordinary-video and stream caps, not a whole-run limit or an exact count. YouTube filters can mix video types."
},
"subtitlesLanguage": {
"enum": [
"any",
"en",
"de",
"es",
"fr",
"it",
"ja",
"ko",
"nl",
"pt",
"ru"
],
"type": "string",
"title": "Subtitle language",
"editor": "select",
"default": "en",
"example": "en",
"enumTitles": [
"Any",
"English",
"German",
"Spanish",
"French",
"Italian",
"Japanese",
"Korean",
"Holland",
"Portuguese",
"Russian"
],
"description": "Optional, default en. Choices: any (an available language), en, de, es, fr, it, ja, ko, nl, pt or ru. Applies when the selected mode retrieves subtitles. any does not request all languages, and this setting does not translate text or guarantee a language track exists."
},
"aiVideoDescription": {
"type": "boolean",
"title": "Add-on: AI video description ($)",
"default": false,
"example": false,
"description": "Optional paid addition, default false. When enabled, AI may generate a time-segmented description using visual and audio content. Preserve only the returned segments and label them as AI-generated; they may be inaccurate and are not a verbatim transcript.",
"sectionCaption": "🤖 AI video analysis ($)"
},
"transcriptionAndSubtitle": {
"enum": [
"NONE",
"ALWAYS_SUBTITLES",
"TRANSCRIPTION_AS_FALLBACK",
"ALWAYS_TRANSCRIBE"
],
"type": "string",
"title": "Transcription & subtitles",
"editor": "select",
"default": "NONE",
"nullable": true,
"enumTitles": [
"None",
"Only download subtitles (when present on the video)",
"Download subtitles + transcribe videos without subtitles (using speech-to-text models) ($)",
"Always transcribe ($)"
],
"description": "Optional, default NONE: skip subtitles and transcription. ALWAYS_SUBTITLES requests existing subtitles when available. TRANSCRIPTION_AS_FALLBACK requests subtitles and uses speech-to-text when subtitles are absent. ALWAYS_TRANSCRIBE requests generated speech text regardless of existing captions. Speech-to-text can add cost. Existing subtitles may appear with records; generated transcripts are stored separately by the supplier and may be returned as references. Complete text access or native file delivery is not guaranteed.",
"sectionCaption": "🖹 Download YouTube transcript"
},
"preferAutoGeneratedSubtitles": {
"type": "boolean",
"title": "Prefer automatically generated subtitles.",
"editor": "hidden",
"example": false,
"description": "Optional. True prefers automatically generated subtitles over uploaded captions when available. Requires a selected subtitle language and a mode that retrieves subtitles. It does not translate captions, guarantee availability or force new speech-to-text generation."
}
},
"description": "Optional settings for a keyword query or selected YouTube URLs, the requested video types, channel controls and subtitle or AI options. Supply a usable query or URL for a useful collection. URLs take priority over queries; search filters apply only to keywords.",
"schemaVersion": 1
}
},
"additionalProperties": false
}
