YouTube Search Results & Entity Type Scraper
Search YouTube by keyword for videos, Shorts, channels, or playlists, with view counts, duration, and channel details, filterable by upload date, duration, sort order, and region.
Input schema
Input fields, types, required flags, descriptions, defaults, and prefills come from the published definition. Prefill examples are distinct from defaults.
| Field | Type | Required | Description |
|---|---|---|---|
searchQueries | array | required | One or more YouTube search terms. Each query is scraped separately and its results are combined in the dataset. |
maxResults | integer | optional | Maximum number of results per query. YouTube may serve fewer rows for a given query, entity type, session, or IP; the run reports the requested and actual counts and whether the result pool was exhausted. |
scrapeAllResults | boolean | optional | Keep loading pages until YouTube stops offering results. This ignores Max Results Per Query and can take longer on broad searches. |
Show all input fields
| Field | Type | Required | Description |
|---|---|---|---|
searchQueries | array | required | One or more YouTube search terms. Each query is scraped separately and its results are combined in the dataset. |
maxResults | integer | optional | Maximum number of results per query. YouTube may serve fewer rows for a given query, entity type, session, or IP; the run reports the requested and actual counts and whether the result pool was exhausted. |
scrapeAllResults | boolean | optional | Keep loading pages until YouTube stops offering results. This ignores Max Results Per Query and can take longer on broad searches. |
sortBy | string | optional | Order of the search results. YouTube currently supports relevance and popularity (view count). Legacy values upload_date and rating are accepted for saved tasks and mapped to relevance with a warning. |
uploadDate | string | optional | Only return results uploaded in the selected period. Applies to videos and Shorts. |
type | string | optional | Restrict results to one entity type. Legacy plural value shorts is accepted and mapped to Shorts. |
duration | string | optional | Filter videos by length. Applies to video and Shorts searches. |
features | array | optional | Filter videos by features. Multiple selections are combined. Legacy aliases cc, location, and purchased are accepted for saved tasks; cc maps to subtitles and the other two are ignored with a warning. |
market | string | optional | Country used for YouTube's search context (gl). Results and labels follow this market. |
language | string | optional | Language for YouTube labels and search text (hl). Auto follows the selected market. |
includeVideoDetails | boolean | optional | Fetch each video's public detail payload to add exact publish date, views, likes, category, tags, and full description. Adds one request per video and makes runs slower. |
Download the published input schema
View complete JSON
{
"description": "Search YouTube by keyword for videos, Shorts, channels, playlists, or movies. Filter by upload date, duration, sort order, features, market, and language. Optional video details add exact publish dates, views, likes, categories, and tags.",
"properties": {
"duration": {
"default": "",
"description": "Filter videos by length. Applies to video and Shorts searches.",
"editor": "select",
"enum": [
"",
"short",
"medium",
"long"
],
"enumTitles": [
"Any duration",
"Under 3 minutes",
"3 to 20 minutes",
"Over 20 minutes"
],
"prefill": "",
"title": "Duration",
"type": "string"
},
"features": {
"default": [],
"description": "Filter videos by features. Multiple selections are combined. Legacy aliases cc, location, and purchased are accepted for saved tasks; cc maps to subtitles and the other two are ignored with a warning.",
"editor": "select",
"items": {
"enumSuggestedValues": [
"hd",
"subtitles",
"creative_commons",
"live",
"4k",
"hdr",
"360",
"vr180",
"3d"
],
"enumTitles": [
"HD",
"Subtitles/CC",
"Creative Commons",
"Live",
"4K",
"HDR",
"360 degrees",
"VR180",
"3D"
],
"type": "string"
},
"prefill": [],
"title": "Video Features",
"type": "array"
},
"includeVideoDetails": {
"default": false,
"description": "Fetch each video's public detail payload to add exact publish date, views, likes, category, tags, and full description. Adds one request per video and makes runs slower.",
"prefill": false,
"title": "Include Video Details",
"type": "boolean"
},
"language": {
"default": "auto",
"description": "Language for YouTube labels and search text (hl). Auto follows the selected market.",
"editor": "select",
"enum": [
"auto",
"ar",
"bn",
"cs",
"da",
"de",
"el",
"en",
"es",
"fa",
"fi",
"fr",
"he",
"hi",
"hu",
"id",
"it",
"ja",
"ko",
"ms",
"nl",
"no",
"pl",
"pt",
"ro",
"ru",
"sv",
"th",
"tr",
"uk",
"ur",
"vi",
"zh-Hans",
"zh-Hant"
],
"enumTitles": [
"Auto (from market)",
"Arabic",
"Bengali",
"Czech",
"Danish",
"German",
"Greek",
"English",
"Spanish",
"Persian",
"Finnish",
"French",
"Hebrew",
"Hindi",
"Hungarian",
"Indonesian",
"Italian",
"Japanese",
"Korean",
"Malay",
"Dutch",
"Norwegian",
"Polish",
"Portuguese",
"Romanian",
"Russian",
"Swedish",
"Thai",
"Turkish",
"Ukrainian",
"Urdu",
"Vietnamese",
"Chinese (Simplified)",
"Chinese (Traditional)"
],
"prefill": "auto",
"title": "Interface Language",
"type": "string"
},
"market": {
"default": "US",
"description": "Country used for YouTube's search context (gl). Results and labels follow this market.",
"editor": "select",
"enum": [
"US",
"GB",
"CA",
"AU",
"DE",
"FR",
"JP",
"KR",
"BR",
"IN",
"MX",
"IT",
"ES",
"NL",
"PL",
"RU",
"SE",
"NO",
"DK",
"FI",
"ZA",
"SG",
"HK",
"TW",
"ID",
"MY",
"TH",
"PH",
"AR",
"CO",
"CL"
],
"enumTitles": [
"United States",
"United Kingdom",
"Canada",
"Australia",
"Germany",
"France",
"Japan",
"South Korea",
"Brazil",
"India",
"Mexico",
"Italy",
"Spain",
"Netherlands",
"Poland",
"Russia",
"Sweden",
"Norway",
"Denmark",
"Finland",
"South Africa",
"Singapore",
"Hong Kong",
"Taiwan",
"Indonesia",
"Malaysia",
"Thailand",
"Philippines",
"Argentina",
"Colombia",
"Chile"
],
"prefill": "US",
"title": "Market",
"type": "string"
},
"maxResults": {
"default": 20,
"description": "Maximum number of results per query. YouTube may serve fewer rows for a given query, entity type, session, or IP; the run reports the requested and actual counts and whether the result pool was exhausted.",
"maximum": 1000,
"minimum": 1,
"prefill": 3,
"title": "Max Results Per Query",
"type": "integer"
},
"scrapeAllResults": {
"default": false,
"description": "Keep loading pages until YouTube stops offering results. This ignores Max Results Per Query and can take longer on broad searches.",
"prefill": false,
"title": "Scrape All Available Results",
"type": "boolean"
},
"searchQueries": {
"description": "One or more YouTube search terms. Each query is scraped separately and its results are combined in the dataset.",
"editor": "stringList",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"prefill": [
"apify"
],
"title": "Search Queries",
"type": "array"
},
"sortBy": {
"default": "relevance",
"description": "Order of the search results. YouTube currently supports relevance and popularity (view count). Legacy values upload_date and rating are accepted for saved tasks and mapped to relevance with a warning.",
"editor": "select",
"enumSuggestedValues": [
"relevance",
"view_count"
],
"enumTitles": [
"Relevance",
"View count (popularity)"
],
"prefill": "relevance",
"title": "Sort By",
"type": "string"
},
"type": {
"default": "",
"description": "Restrict results to one entity type. Legacy plural value shorts is accepted and mapped to Shorts.",
"editor": "select",
"enumSuggestedValues": [
"",
"video",
"short",
"channel",
"playlist",
"movie"
],
"enumTitles": [
"All",
"Videos",
"Shorts",
"Channels",
"Playlists",
"Movies"
],
"prefill": "video",
"title": "Result Type",
"type": "string"
},
"uploadDate": {
"default": "",
"description": "Only return results uploaded in the selected period. Applies to videos and Shorts.",
"editor": "select",
"enum": [
"",
"last_hour",
"today",
"this_week",
"this_month",
"this_year"
],
"enumTitles": [
"Any time",
"Last hour",
"Today",
"This week",
"This month",
"This year"
],
"prefill": "",
"title": "Upload Date",
"type": "string"
}
},
"required": [
"searchQueries"
],
"schemaVersion": 1,
"title": "YouTube Search Scraper Input",
"type": "object"
}
Output schema
Published result links and storage locations. This schema is not an exhaustive contract for every field in a dataset record.
| Field | Type | Required | Description |
|---|---|---|---|
results | string | optional | Dataset containing all scraped YouTube search result rows. |
Download the published output schema
View complete JSON
{
"actorOutputSchemaVersion": 1,
"description": "Search result rows for videos, Shorts, channels, playlists, and movies, with optional exact dates, views, likes, categories, tags, and live or upcoming state.",
"properties": {
"results": {
"description": "Dataset containing all scraped YouTube search result rows.",
"template": "{{links.apiDefaultDatasetUrl}}/items",
"title": "YouTube Search Scraper dataset",
"type": "string"
}
},
"title": "YouTube Search Results & Entity Type Scraper Output"
}
Dataset schema
Published dataset views and any declared field definitions. A view can select only a subset of the returned record fields.
Download the published dataset schema
View complete JSON
{
"actorSpecification": 1,
"title": "YouTube Search Results",
"views": {
"detailed": {
"display": {
"component": "table",
"properties": {
"badge": {
"format": "text",
"label": "Badge"
},
"badges": {
"format": "text",
"label": "Badges"
},
"category": {
"format": "text",
"label": "Category"
},
"channelHandle": {
"format": "text",
"label": "Channel Handle"
},
"channelId": {
"format": "text",
"label": "Channel ID"
},
"channelName": {
"format": "text",
"label": "Channel"
},
"channelUrl": {
"format": "link",
"label": "Channel URL"
},
"channelVerified": {
"format": "boolean",
"label": "Channel Verified"
},
"concurrentViewers": {
"format": "number",
"label": "Concurrent Viewers"
},
"description": {
"format": "text",
"label": "Description"
},
"duration": {
"format": "text",
"label": "Duration"
},
"durationSeconds": {
"format": "number",
"label": "Duration (s)"
},
"durationText": {
"format": "text",
"label": "Duration Text"
},
"estimatedResults": {
"format": "number",
"label": "Estimated Results"
},
"firstVideoId": {
"format": "text",
"label": "First Video ID"
},
"fullDescription": {
"format": "text",
"label": "Full Description"
},
"handle": {
"format": "text",
"label": "Handle"
},
"isLive": {
"format": "boolean",
"label": "Live"
},
"isShort": {
"format": "boolean",
"label": "Short"
},
"isUpcoming": {
"format": "boolean",
"label": "Upcoming"
},
"isVerified": {
"format": "boolean",
"label": "Verified"
},
"likeCount": {
"format": "number",
"label": "Likes"
},
"ownerName": {
"format": "text",
"label": "Owner"
},
"playlistId": {
"format": "text",
"label": "Playlist ID"
},
"position": {
"format": "number",
"label": "Position"
},
"publishedAt": {
"format": "text",
"label": "Published At"
},
"publishedTimeText": {
"format": "text",
"label": "Published"
},
"richThumbnailUrl": {
"format": "link",
"label": "Rich Thumbnail"
},
"scheduledStartTime": {
"format": "text",
"label": "Scheduled Start"
},
"scrapedAt": {
"format": "text",
"label": "Scraped At"
},
"searchQuery": {
"format": "text",
"label": "Search Query"
},
"subscriberCount": {
"format": "number",
"label": "Subscribers"
},
"subscriberCountText": {
"format": "text",
"label": "Subscribers Text"
},
"tags": {
"format": "text",
"label": "Tags"
},
"title": {
"format": "text",
"label": "Title"
},
"type": {
"format": "text",
"label": "Type"
},
"url": {
"format": "link",
"label": "URL"
},
"videoCount": {
"format": "number",
"label": "Video Count"
},
"videoCountText": {
"format": "text",
"label": "Video Count Text"
},
"videoId": {
"format": "text",
"label": "Video ID"
},
"viewCount": {
"format": "number",
"label": "Views"
},
"viewCountText": {
"format": "text",
"label": "Views Text"
}
}
},
"title": "Detailed View",
"transformation": {
"fields": [
"position",
"type",
"videoId",
"title",
"description",
"fullDescription",
"channelName",
"channelId",
"channelUrl",
"channelHandle",
"channelVerified",
"viewCount",
"viewCountText",
"likeCount",
"category",
"tags",
"duration",
"durationText",
"durationSeconds",
"publishedAt",
"publishedTimeText",
"isLive",
"isUpcoming",
"scheduledStartTime",
"concurrentViewers",
"badges",
"richThumbnailUrl",
"isVerified",
"subscriberCount",
"subscriberCountText",
"videoCount",
"videoCountText",
"playlistId",
"firstVideoId",
"ownerName",
"handle",
"badge",
"isShort",
"url",
"estimatedResults",
"searchQuery",
"scrapedAt"
]
}
},
"overview": {
"display": {
"component": "table",
"properties": {
"channelName": {
"format": "text",
"label": "Channel"
},
"duration": {
"format": "text",
"label": "Duration"
},
"position": {
"format": "number",
"label": "Position"
},
"publishedAt": {
"format": "text",
"label": "Published At"
},
"publishedTimeText": {
"format": "text",
"label": "Published"
},
"searchQuery": {
"format": "text",
"label": "Search Query"
},
"title": {
"format": "text",
"label": "Title"
},
"type": {
"format": "text",
"label": "Type"
},
"url": {
"format": "link",
"label": "URL"
},
"videoId": {
"format": "text",
"label": "Video ID"
},
"viewCount": {
"format": "number",
"label": "Views"
}
}
},
"title": "Results Overview",
"transformation": {
"fields": [
"position",
"type",
"videoId",
"title",
"channelName",
"viewCount",
"publishedAt",
"publishedTimeText",
"duration",
"url",
"searchQuery"
]
}
}
}
}
Key-value schema
Published key-value store definitions, when provided by this build.
This definition is not present in the default published build. See the published README for available documentation.
Published README
Read the full published documentation
YouTube Search Results & Entity Type Scraper
Search YouTube without cookies or API keys and get structured rows for videos, Shorts, channels, playlists, and movies. Use YouTube's own filters, follow pagination, and optionally enrich every video with exact views and likes, dates when YouTube exposes them, and categories or tags when available.
What this actor does
- Five result types: videos, Shorts, channels, playlists, and movies.
- All-result mode: mix the entity types in YouTube's own order.
- Server-side filters: upload date, duration, sort order, video features, market, and interface language.
- Pagination: follow continuation tokens until your limit or YouTube's own ceiling.
- Optional details: one detail request per video (plus fallback calls when needed) adds exact views and likes, dates when exposed, tags, and the full description.
- Bulk queries: run several searches in one job.
- Cookieless: public search data only. No login, no browser, no proxy setup.
- Omit-empty output: a row only contains values that are actually available.
Input
| Field | Type | Default | Description |
|---|---|---|---|
searchQueries |
array | — | One or more YouTube search terms. Duplicate terms are removed. |
maxResults |
integer | 20 |
Results per query (1-1000). YouTube caps each entity type below 1000. |
scrapeAllResults |
boolean | false |
Follow pages until YouTube stops returning results, ignoring maxResults. |
sortBy |
string | relevance |
relevance or view_count. YouTube no longer supports date or rating sorting. |
uploadDate |
string | any | last_hour, today, this_week, this_month, or this_year. |
type |
string | all | video, short, channel, playlist, or movie. |
duration |
string | any | short (under 3 min), medium (3-20 min), or long (over 20 min). |
features |
array | [] |
hd, subtitles, creative_commons, live, 4k, hdr, 360, vr180, 3d. Multiple values are combined. |
market |
string | US |
Country used for YouTube's search context. 31 markets are available. |
language |
string | auto |
Interface language. auto follows the market. |
includeVideoDetails |
boolean | false |
Fetch each video's detail payload for exact views, likes, and duration, plus dates, category, tags, and the full description when YouTube exposes them. |
Example: video search
{
"searchQueries": ["web scraping tutorial", "python automation"],
"maxResults": 50,
"type": "video",
"sortBy": "view_count",
"uploadDate": "this_year"
}
Example: Shorts
{
"searchQueries": ["lofi beats"],
"type": "short",
"maxResults": 100
}
Example: channels
{
"searchQueries": ["python tutorials"],
"type": "channel",
"market": "GB"
}
Example: exact video details
{
"searchQueries": ["apify"],
"type": "video",
"maxResults": 20,
"includeVideoDetails": true
}
Output
Every result row has type, position (1-based within the query), searchQuery, and scrapedAt. When YouTube exposes an estimate for the query, estimatedResults is added to each row.
Video and movie rows
| Field | Example |
|---|---|
| videoId | "dQw4w9WgXcQ" |
| title | "Never Gonna Give You Up" |
| url | "https://www.youtube.com/watch?v=dQw4w9WgXcQ" |
| description | result-card snippet |
| channelName | "Rick Astley" |
| channelId | "UCuAXFkgsw1L7..." |
| channelUrl | "https://www.youtube.com/@RickAstley" |
| channelHandle | "@RickAstley" when the byline links to a handle |
| channelVerified | true when the uploader has a verified badge |
| viewCount | exact integer when the card or details provide one |
| viewCountText | "1.6B views" or "42,963 views" (verbatim) |
| publishedTimeText | "2 years ago" |
| publishedAt | ISO 8601 UTC timestamp when a full time is exposed (includeVideoDetails only) |
| likeCount | exact integer (includeVideoDetails only) |
| category | "Science & Technology" when exposed (includeVideoDetails only) |
| tags | array of video keywords when exposed (includeVideoDetails only) |
| fullDescription | full description text (includeVideoDetails only) |
| duration | "3:33" |
| durationSeconds | 213 |
| thumbnails | array of {url, width, height} |
| richThumbnailUrl | animated preview URL when available |
| badges | result-card badges such as ["CC", "4K"] |
| isLive | true for a live broadcast |
| isUpcoming | true for a scheduled premiere or live event |
| scheduledStartTime | ISO 8601 start time for upcoming videos (includeVideoDetails only) |
| concurrentViewers | current viewer count on a live card |
Channel rows
| Field | Example |
|---|---|
| channelId | "UCxxxxxx" |
| channelName | "Python Programmer" |
| channelUrl | "https://www.youtube.com/@gilesmcmullen" |
| handle | "@gilesmcmullen" |
| channelHandle | same handle, for consistency with video rows |
| description | search-card snippet |
| subscriberCount | approximate integer from YouTube's rounded label |
| subscriberCountText | "782K subscribers" |
| videoCount / videoCountText | only when YouTube shows a video count on the card |
| thumbnails | array of avatar images |
| isVerified | true or false |
Playlist and course rows
| Field | Example |
|---|---|
| playlistId | "PLxxxxxxx" |
| title | "Python Full Course" |
| url | "https://www.youtube.com/playlist?list=PLxxxxxxx" |
| channelName | "CodeWithHarry" |
| channelId | "UCxxxxxx" |
| channelUrl | "https://www.youtube.com/@CodeWithHarry" |
| channelHandle | "@CodeWithHarry" |
| videoCount / videoCountText | 100 / "100 lessons" when available |
| firstVideoId | first video shown on the card |
| thumbnails | array of playlist thumbnails |
Shorts rows
| Field | Example |
|---|---|
| videoId | "abc123" |
| title | "A short example" |
| url | "https://www.youtube.com/shorts/abc123" |
| viewCount | exact integer only when YouTube shows an unabridged count |
| viewCountText | "1.2M views" (verbatim) |
| thumbnails | vertical thumbnails |
| badge | card badge when present |
| isShort | true |
With includeVideoDetails, Shorts also gain channelName, channelId, channelUrl, channelHandle, publishedAt, likeCount, durationSeconds, category, and tags.
Status rows
A typed query with no results produces one status row: recordType: "status", status: "no_results", query, market, resultType, appliedFilters, and resultCount: 0. A failed query produces status: "query_failed" with an error string.
How row limits work
YouTube serves a variable number of results for the same query. There is no fixed ceiling: the same news query returned 343-373 videos, 14-24 Shorts, 601-685 mixed rows, 134-367 channels, 357-461 playlists, and 204 movies on different runs and IPs. Set scrapeAllResults to follow pages until YouTube stops offering results, or use maxResults for a smaller slice. When the requested count is not reached, the status message reports the requested and actual counts and whether the query pool was exhausted, stopped after repeated empty pages, or lost its continuation. It does not claim a fixed ceiling.
Limitations
- Date and rating sorts are not available. YouTube removed them; the UI suggests only relevance and view count. Saved tasks that still send
sortBy: "upload_date"or"rating"are accepted and mapped to relevance with a warning. - Subscriber counts are rounded. YouTube only publishes display labels for search results, so
subscriberCountis an approximation andsubscriberCountTextis the verbatim label. Localized labels are parsed, including Japaneseチャンネル登録者数 184万人and Korean구독자 8.65만명. - Some exact fields need a full player response. On datacenter IPs YouTube can return a reduced response. Exact views, likes, and duration normally resolve, but
publishedAtcan be date-only or absent andcategory/tagscan be omitted. The actor never fills these with zero or a placeholder. - Live view counts are a live counter. For an active stream, the detail
viewCountfollows the current live counter and is not comparable to lifetime views. UseconcurrentViewerson the card for the live audience. - Shorts can stop early. Repeated empty continuation pages can end a Shorts run before the requested count. The run succeeds and the status message reports the requested and actual counts.
- No comment counts. Comments are handled by the dedicated YouTube comments actor.
- Shorts cards are sparse. Without
includeVideoDetails, YouTube does not expose channel, date, duration, or exact views on a Shorts card. - Movies are YouTube's "Movies" filter. It returns movie-catalog videos; some are full films, some are clips or episodes.
- Results vary between runs. YouTube personalizes and re-ranks search results over time.
- Detail fields can be withheld. On some datacenter IPs YouTube returns a limited player response. The actor tries a second player client and the watch-next payload; fields that remain unavailable (
viewCount,category,tags,publishedAt) are omitted, never filled with zero or a placeholder. - Location and Purchased filters are not offered. They return no cookieless results. Saved tasks that send
features: ["location"],["purchased"], or["cc"]are accepted:ccmaps to subtitles, the other two are ignored with a warning.
FAQ
Do I need cookies or a YouTube API key?
No. The actor reads public search results with no credentials.
Which result types can I request?
Videos, Shorts, channels, playlists, and movies. Leave type empty for mixed results. Saved tasks that send the plural shorts are mapped to the Shorts type.
Why did I get fewer rows than maxResults?
YouTube serves a variable number of rows and there is no fixed ceiling. The status message reports the requested and actual counts and whether the query pool was exhausted or stopped after repeated empty pages. Some Shorts searches can stop early; the same shortfall message applies.
What does includeVideoDetails add?
Exact views, likes, and duration, plus publish date, category, tags, full description, and upcoming/live state when YouTube exposes them. It costs one or more requests per video and makes the run slower.
Why is viewCount missing on some rows?
YouTube shows rounded labels such as 1.6B views on many cards. The actor keeps viewCountText but does not turn a rounded label into a fake exact number. Enable includeVideoDetails for exact views.
Why is a channel's subscriber count approximate?
Search cards only show rounded labels such as 782K subscribers.
Are Shorts supported without details?
Yes. Title, URL, views text, and thumbnails are available. Channel, date, duration, and exact views require includeVideoDetails.
Can I run several searches at once?
Yes. Add them to searchQueries; each query gets its own position sequence and searchQuery value.
Python quickstart
Use a schema-derived input and the Python standard library to start a run. An Apify account and token are required for execution.
Source build dDxnim0EkVlo74Ldw. Documentation is regenerated from the default published build; private drafts are not included.