Youtube Search Actor

This Apify actor allows you to perform various search operations on YouTube, including standard video/channel/playlist search, fetching auto-complete suggestions, searching YouTube Music, and finding videos by a specific hashtag.

⚙️ Input Parameters

The actor's behavior is controlled by the input JSON. Below are the available fields.

Primary Configuration

These fields control the main operation of the actor.

• operation (Required)

  • Description: Select the search operation to perform.
  • Type: string
  • Default: "search"
  • Options:
    • search: Standard YouTube search for videos, channels, playlists, etc.
    • search: Get search auto-complete suggestions for a query.
    • music-search: Search on YouTube Music.
    • hashtag: Find videos for a specific hashtag.

• query (Required)

  • Description: The search term you want to use. This is required for search, suggestions, and music-search operations.
  • Type: string
  • Default: "mr beast"

  Note: This field is marked as required by the schema. Even if you are using the hashtag operation (which doesn't use query), you must provide a value (e.g., "placeholder").

• hashtag

  • Description: The hashtag to search for. Do not include the # symbol. This is used only for the hashtag operation.
  • Type: string
  • Example: "cooking"

• page

  • Description: The page number of the results to fetch.
  • Type: integer
  • Default: 1

General Search Filters (for operation: "search")

These filters apply only when operation is set to search.

• sortBy

  • Description: How to sort the search results.
  • Type: string
  • Default: "relevance"
  • Options: relevance, rating, upload_date, view_count

• type

  • Description: Filter the search results by content type.
  • Type: string
  • Default: "all"
  • Options: all, video, channel, playlist, movie

• duration

  • Description: Filter videos by their duration.
  • Type: string
  • Default: "all"
  • Options:
    • all: Any duration
    • short: Less than 4 minutes
    • medium: 4-20 minutes
    • long: More than 20 minutes

• uploadDate

  • Description: Filter results by when they were uploaded.
  • Type: string
  • Default: "all"
  • Options:
    • all: All Time
    • hour: Last Hour
    • today: Today
    • week: This Week
    • month: This Month
    • year: This Year

• feature

  • Description: Filter by specific video features. You can combine multiple features by separating them with a comma (e.g., hd,subtitles).
  • Type: string
  • Example: "hd,subtitles,4k"

Music Search Filters (for operation: "music-search")

This filter applies only when operation is set to music-search.

• musicType
  • Description: Filter YouTube Music search results by type.
  • Type: string
  • Default: "all"
  • Options: all, song, video, album, playlist, artist

🚀 Usage Examples (JSON Input)

Here are a few examples of valid JSON inputs for different tasks.

1. Standard Search (Filtered)

Find popular videos about Python tutorials uploaded this year.

{
  "operation": "search",
  "query": "python tutorial",
  "sortBy": "view_count",
  "type": "video",
  "uploadDate": "year"
}

2. Get Search Suggestions

Get auto-complete suggestions for the query "how to cook".

{
  "operation": "suggestions",
  "query": "how to cook"
}

3. Search YouTube Music

Find playlists on YouTube Music matching "lofi beats".

{
  "operation": "music-search",
  "query": "lofi beats",
  "musicType": "playlist"
}

4. Search by Hashtag

Find videos tagged with #apify.

{
  "operation": "hashtag",
  "hashtag": "apify",
  "query": "placeholder"
}

📤 Output

The actor pushes its results to the Apify dataset.

Successful Run

For a successful run, the dataset will contain objects representing the results of your query. The structure of these objects will vary depending on the operation you selected (e.g., a list of videos for search, a list of suggestions for suggestions, etc.).

Error

If an error occurs, the actor will push a single object to the dataset with the following structure, detailing what went wrong:

{
  "data": null,
  "error": "Error message describing what went wrong",
  "timestamp": "2025-11-18T17:00:00.000Z"
}