Vexaloom Labs

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.

FieldTypeRequiredDescription
searchQueriesarrayrequiredOne or more YouTube search terms. Each query is scraped separately and its results are combined in the dataset.
maxResultsintegeroptionalMaximum 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.
scrapeAllResultsbooleanoptionalKeep loading pages until YouTube stops offering results. This ignores Max Results Per Query and can take longer on broad searches.
Show all input fields
FieldTypeRequiredDescription
searchQueriesarrayrequiredOne or more YouTube search terms. Each query is scraped separately and its results are combined in the dataset.
maxResultsintegeroptionalMaximum 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.
scrapeAllResultsbooleanoptionalKeep loading pages until YouTube stops offering results. This ignores Max Results Per Query and can take longer on broad searches.
sortBystringoptionalOrder 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.
uploadDatestringoptionalOnly return results uploaded in the selected period. Applies to videos and Shorts.
typestringoptionalRestrict results to one entity type. Legacy plural value shorts is accepted and mapped to Shorts.
durationstringoptionalFilter videos by length. Applies to video and Shorts searches.
featuresarrayoptionalFilter 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.
marketstringoptionalCountry used for YouTube's search context (gl). Results and labels follow this market.
languagestringoptionalLanguage for YouTube labels and search text (hl). Auto follows the selected market.
includeVideoDetailsbooleanoptionalFetch 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.

FieldTypeRequiredDescription
resultsstringoptionalDataset 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.
{
  "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 subscriberCount is an approximation and subscriberCountText is 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 publishedAt can be date-only or absent and category/tags can 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 viewCount follows the current live counter and is not comparable to lifetime views. Use concurrentViewers on 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: cc maps 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.

Open the step-by-step Python guide →

Source build dDxnim0EkVlo74Ldw. Documentation is regenerated from the default published build; private drafts are not included.