YouTube Scraper — Search, Channels and Shorts

Export public YouTube video listings from keyword search, channel Videos/Shorts/Live tabs, or individual video URLs. One flat, never-null schema; optional video details are included at the same per-video price. No YouTube API key, login, cookies or video downloads.

For comment text and linked replies, use YouTube Comments Scraper. This Actor returns video rows, not comment rows.

Quick start

{"searchQueries":["lofi hip hop"],"maxResults":10}

Channel uploads:

{"startUrls":["@MrBeast"],"channelTab":"videos","maxResults":50}

Shorts:

{"startUrls":["https://www.youtube.com/@MrBeast"],"channelTab":"shorts","maxResults":50}

Exact displayed date and additional metadata:

{"startUrls":["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],"includeDetails":true}

Search date filter:

{"searchQueries":["iphone 17 review"],"uploadDate":"week","maxResults":40}

Input

Field	Default	Meaning
searchQueries	[]	Keyword strings, one result limit per query.
startUrls	[]	Video ID, watch/Shorts/youtu.be URL, channel @handle or /channel/UC… /c/… /user/… URL, or /results?search_query= URL.
maxResults	50	Unique videos per query/channel, 1–5,000. Direct video input returns one row. Default prefill is 10 results.
channelTab	videos	videos, shorts or streams. A missing channel tab returns no_results.
uploadDate	any	Search only: any, today, week, month or year. Read from the current public filter menu.
sortBy	relevance	Only relevance is supported. YouTube's measured menu does not expose Sort by upload date.
includeDetails	false	Add exact displayed calendar date, likes, full public description and comment count. No extra charge per result.
language	en	Listing UI language. Channel metadata, filter discovery and exact-date enrichment use English for reliable parsing.
country	US	Two-letter country code sent as gl.

At most 100 combined inputs. Duplicate normalized inputs and repeated videos within each input are removed. The same video found under different queries may appear once per query. Unsupported inputs yield free failed rows. Past hour and sortBy=date are explicitly rejected; they are not silently approximated. Search skips Shorts shelves; use a channel's Shorts tab for Shorts.

Output

Each result has all 32 keys, without null. Missing strings are "", counts are 0, badges are [].

Field	Meaning
inputIndex, input	Original combined input index and supplied query/URL. Queries precede URLs.
source, query	search, channel or video; keyword when applicable.
videoId, url, title, type	Canonical ID/link/title; video, short or live.
channelName, channelId, channelUrl, channelHandle	Available public channel identity. Handle excludes @.
subscribersText, subscribers	Displayed subscriber label and numeric interpretation; often absent in search.
viewCountText, viewCount	Raw displayed views or live viewer label and numeric interpretation.
publishedTimeText, publishedAt	Raw relative date; exact displayed date YYYY-MM-DD only with details and when available.
durationText, durationSeconds	Displayed duration and parsed seconds; 0 when unavailable or live.
isLive	Whether the public response identifies a current live stream. Past streams are videos.
likeCount, commentCount, description	Detail enrichment; 0/0/"" without details or when unavailable.
thumbnail, badges	Public thumbnail URL and badge labels.
position, detailsIncluded	One-based returned position for this input; whether detail enrichment ran.
status, subStatus, error, scrapedAt	Stable outcome, machine-readable reason, explanation and ISO scrape timestamp.

The details path reads the public video next response and, when needed, the first public comment page for its count. It does not collect comment text into results. Individual video URLs also require next to identify the video even when includeDetails is false. That endpoint does not expose a reliable duration, so direct video duration may be empty/0. Channel tab data does not always expose a handle or a publish date, especially for Shorts.

status	subStatus	Charged video event
ok	video	Yes
no_results	no_results	No
failed	invalid_input, not_found, http_CODE, blocked, parse_error, network_error, free_work_limit, cost_limit_reached	No

A partial input can return saved videos and a final free failure/limit row. Failed detail enrichment produces free failure rows instead of charging an incomplete enriched result.

Pricing

One video event per saved successful video, including optional details. No per-query, date-filter or Shorts surcharge.

Apify tier	Per video	Per 1,000
FREE	$0.001	$1.00
BRONZE	$0.0008	$0.80
SILVER	$0.0006	$0.60
GOLD+	$0.0004	$0.40

Default Actor start fee: $0.00005 per start event (per GB, minimum one). Failed and empty rows have no video charge; the start fee still applies. Dataset-item billing is disabled. The Actor pays platform usage under PPE. Your configured spending limit may stop results early.

API examples

Replace APIFY_TOKEN with your own token; do not paste it into input.

curl -X POST "https://api.apify.com/v2/acts/sumitr_mardy~youtube-scraper/run-sync-get-dataset-items?format=json" \
  -H "Authorization: Bearer $APIFY_TOKEN" -H "Content-Type: application/json" \
  -d '{"searchQueries":["lofi hip hop"],"maxResults":10}'

import os
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("sumitr_mardy/youtube-scraper").call(
    run_input={"startUrls": ["@MrBeast"], "channelTab": "shorts", "maxResults": 50}
)
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["videoId"], row["title"], row["viewCount"])

For larger jobs use asynchronous runs, then download the dataset as JSON, CSV or Excel.

Use it from AI agents (MCP)

Hosted OAuth:

{"mcpServers":{"youtube":{"url":"https://mcp.apify.com/?tools=sumitr_mardy/youtube-scraper"}}}

Hosted Bearer alternative:

{"mcpServers":{"youtube":{"url":"https://mcp.apify.com/?tools=sumitr_mardy/youtube-scraper","headers":{"Authorization":"Bearer YOUR_APIFY_TOKEN"}}}}

Stdio:

{"mcpServers":{"youtube":{"command":"npx","args":["-y","@apify/actors-mcp-server","--tools","sumitr_mardy/youtube-scraper"],"env":{"APIFY_TOKEN":"YOUR_APIFY_TOKEN"}}}}

Ask your agent to search a keyword, list channel uploads or export Shorts; set maxResults explicitly. Enable details only when you need dates, likes or descriptions. Always inspect status/subStatus before using counts.

Limits and data accuracy

Public data only. Not affiliated with YouTube or Google. No player endpoint, video/audio downloads, transcripts, private videos or login. Public availability and JSON structures can change. Country and public moderation can change visible results; the Actor does not bypass availability restrictions.

Without details dates remain relative. Displayed views, subscribers and likes can be rounded; numeric values interpret that display and are not hidden exact statistics. Details can expose exact displayed views/likes and calendar dates, but a field YouTube does not expose remains empty/0. Comment counts are YouTube's displayed header count and may include unavailable comments. Shorts listing dates/durations can be absent. Details do not guarantee every field on every video.

Current date filters: Today, This week, This month and This year. Sort by upload date and Past hour were absent in both local and Apify responses on 2026-10-30; they are not supported. Result inventory can run out before maxResults. The run has bounded deadlines, a free-work loss guard, two parallel inputs and at most three simultaneous detail calls. Blocking is retried once directly, then once through Apify's default datacenter pool; no residential proxy or cookies.