YouTube Shorts Competitor & Viral Trend Radar

Monitor public Shorts from competitor channels and search queries. Save observations, measure view growth between runs, and rank videos whose measured view velocity is increasing.

This Actor makes its own HTTP requests to YouTube. It does not call other Actors, require a YouTube API key, download video/audio, or use a paid data API. Optional proxy traffic has its own cost.

Quick start

Paste this into Input → JSON:

{
  "channelUrls": ["https://www.youtube.com/@NASA/shorts"],
  "searchQueries": [],
  "maxAgeDays": 0,
  "maxShorts": 5,
  "maxDetailRequests": 15,
  "saveHistory": true,
  "historyProfile": "nasa-demo"
}

Publication-age filtering is off by default (maxAgeDays: 0). This includes videos whose publication date is unavailable; it does not mean those videos are recent. Set a positive value only when you want strict date filtering: unknown dates will then be excluded. Existing saved inputs/tasks may retain 90 and must be changed explicitly.

Run with 512 MB memory and 300 seconds timeout. The collection budget defaults to 180 seconds, reserving time for storage writes. Empty channel and query lists use NASA as a public demo source.

The first successful run gives a baseline with current views, metadata and lifetime-average pace where available. Keep the same sources, country and history profile, then run again at least 60 minutes later to measure growth. A third suitably spaced observation is needed for acceleration. A daily task can provide longer-window measurements; this package does not create schedules automatically.

For niche discovery, use examples/niche-search.json. A run can combine channels and queries. The country setting localizes YouTube discovery; it is not a creator-country or audience-country filter.

What is returned

Each dataset row contains one observed Short. Repeated runs may return the same video with a new observation; this is deliberate monitoring behavior.

Field	Meaning
videoId, url	Video identifier and canonical Shorts link
title, description, hashtags	Public text metadata
channel, channelId, channelUrl	Public channel identity
views	Exact numeric public counter required for a usable observation
likes, comments	Public counters when available; otherwise null
commentsDisplayEstimate	Rounded comment label, when available; excluded from engagement calculation
subscribers, subscribersApproximate	Displayed subscriber count and rounding flag
publishedAt, publishedAtPrecision	Publication time/date reported by YouTube
ageHours	Time since reported publication; date-only sources are less precise
averageViewsPerHourSincePublished	Total views ÷ age in hours; requires timestamp precision and age ≥ 1 hour
averageViewsPerDaySincePublished	Lifetime hourly average × 24; not measured views gained in the last day
measuredViewsPerHour	Difference in exact views ÷ elapsed observation hours
viewsDelta, comparisonHours, baselineAt	Evidence for the measured velocity
priorMeasuredViewsPerHour, velocityRatio	Previous interval velocity and current/previous ratio
likeRatePct	100 × likes / views, when available
engagementRatePct	100 × (likes + exact comments) / views; null if either counter is unavailable
viralScore	0–100 ranking heuristic; null until velocity is measurable
hookSignals, hookAnalysisBasis	English phrase/punctuation rules applied to the title only
firstSeenAt, observedAt, discoveredIn	Collection provenance
shortsEvidence, metricWarnings	Shorts classification evidence and missing metrics
metadataSource, viewsSource, playerStatus	Which metadata path supplied the row and whether the player was available

Shares, retention, watch time, engaged views, audience geography and the spoken/visual opening of the video are not collected. A hook flag is not proof that viewers liked the opening. No score is a probability of becoming viral or evidence of future saturation.

State definitions

State	Interpretation
BASELINE	First observation in a new history profile
NEW	Video first observed after this profile was established; it may have been published earlier
INSUFFICIENT_INTERVAL	Existing video, but no saved observation sufficiently far apart
STALE_BASELINE	Previous observations exceed maxComparisonHours
STABLE	Measurable velocity below the configured rising threshold
RISING	Measured velocity ≥ risingViewsPerHour (default 100)
ACCELERATING	Three suitably spaced observations; current velocity ≥ rising threshold and current/previous velocity ≥ accelerationFactor (default 1.5)
DECLINING	Previous velocity ≥ rising threshold and current/previous velocity ≤ 1 / accelerationFactor; total views can still be increasing
COUNTER_CORRECTION	Public views fell versus the last saved count; the comparison series restarts without a negative growth signal

If previous velocity is zero, the ratio is undefined and remains null. Intervals need not be equal: each rate is divided by its own elapsed hours. Intervals must fall between minIntervalMinutes and maxComparisonHours. These are interval averages and do not establish the exact moment a spike started.

Transparent score

heuristic-v1 is:

min(70, 14 × log10(1 + measuredViewsPerHour))
+ min(20, 2 × likeRatePct)
+ min(10, 10 × max(0, velocityRatio - 1))

Unavailable likes or acceleration contribute no points; the original metric remains null. The score is intentionally absent on a baseline run. Missing metadata can lower a score, so inspect metricWarnings when comparing videos. The score favors absolute measured pace and has not been statistically validated as a prediction model.

Discovery and limits

• Channels are read from their Shorts tab. Searches use YouTube's Shorts filter and Shorts result renderers. Video length alone is not used to call an ordinary video a Short.
• Metadata comes from the public watch-page JSON. If the player is unavailable, the Actor can read exact counters and metadata independently exposed in the same anonymous public page. It validates the video identity and reads only the main video column. If both paths are unavailable, it returns an explicit error.
• Default discovery: up to 30 candidates per source, at most 2 pages per source. Up to 10 channels and 10 queries.
• Previous history candidates and newly discovered candidates are interleaved so the Actor can recheck videos that disappear from a search sample.
• maxShorts limits output rows, while maxDetailRequests caps attempted detail requests including filtered/failed videos. minViews and maxAgeDays filter rows after details are obtained.
• Rows are written progressively. Once maxShorts is reached, collection stops. The report/dashboard ranks the collected output sample, not all candidate videos or all of YouTube.
• Discovery is a bounded, localized sample and can vary between runs. Search-result totals and sampled growth do not prove market-wide or niche-wide growth.

YouTube can block datacenter traffic or change page structures. Configure proxyConfiguration if needed; success on a development machine does not guarantee success on an Apify cloud IP. The Actor does not sign in or request protected playback. A player denial alone does not mean all publicly returned text metadata is unavailable. No missing values are reconstructed from rounded labels. A verified Short with unavailable comments still produces a useful row with comments: null.

Persistent history

History is kept in a named key-value store. Its name is derived from the Actor ID, historyProfile, normalized source lists and country. It is isolated from the default run storage and from other source profiles. Keep these inputs unchanged for comparisons; output filters and thresholds can change without resetting the profile.

The store keeps immutable run snapshots and reads/merges the newest five. Old snapshots are pruned to 60; each compact state retains up to 5,000 videos seen in the last 30 days and up to 100 spaced observations per video. Older history is not a permanent archive. For predictable comparisons, avoid overlapping runs of the same profile; a burst of more than five overlapping runs is outside the supported concurrency envelope.

Snapshots retain counters and provenance, not complete video descriptions. Successfully observed videos filtered out by age/views can be remembered without producing a paid dataset row. Failed video requests do not delete a baseline. No deletion/takedown is inferred from a missing search result. An output-write error prevents this run from saving history because the dataset outcome is uncertain.

Outputs and failure reporting

• Dataset: progressively saved rows; export using Apify's standard JSON/CSV/Excel options.
• OUTPUT: status, coverage, source results, errors, request/byte counters, history status, state counts, appliedFilters and filterCounts explaining exclusions.
• REPORT: summary plus collected rows sorted by score, then lifetime-average pace.
• DASHBOARD: self-contained HTML table linking to observed Shorts.

OUTPUT.status can be SUCCEEDED, PARTIAL or FAILED. The Apify run itself may succeed with PARTIAL output if useful rows were collected before an error or limit. Always check OUTPUT, including historySaved. A valid source with all videos excluded by filters can succeed with zero rows. A run with no detectable Shorts or no verifiable observations after errors fails explicitly.

Costs and monetization

The package uses native apify-default-dataset-item billing if configured by the owner. It checks the remaining event budget before collection and each write, and does not manually charge the same row again. An optional apify-actor-start event is handled by the platform. The package does not configure prices or publish the Actor.

Every emitted observation is a result, including baseline/stable observations. A monitor can consume network/compute while filters exclude all results. Keep a small startup fee or platform-usage billing under consideration only after cloud cost tests. Residential proxy transfer can dominate compute costs: full public pages are substantially larger than output rows. OUTPUT.http.bytes records response-body bytes, not the final billable proxy total. No profit margin is claimed from local testing.

Before publication, run two small cloud tests with the same profile, verify history survives under Limited permissions, inspect actual usage/transfer cost, and verify the chosen default input produces a nonempty dataset. For measured velocity, space runs at least one hour apart. Real acceleration requires a third such run. Do not advertise a guarantee of detecting Shorts before saturation.

Develop and deploy

Node.js 22 or newer is required. npm ci, npm test, npm run check, then apify validate-schema. bash deploy.sh performs these checks and runs apify push. It targets youtube-shorts-trend-radar in your logged-in Apify account; it does not publish to Store or alter other Actors.

The Dockerfile uses apify/actor-node:22. Runtime dependencies are pinned and accompanied by a lockfile. No Python, FFmpeg, browser or third-party Actor is required.

Optional public-network tests:

npm run test:live
node test/sdk-live.mjs
node test/public-live.mjs

The SDK test uses temporary local storage and two actual public collections; it never starts a cloud Actor. It verifies baseline reuse without inventing elapsed time. Unit tests cover spaced growth and acceleration using controlled timestamps.

References

• Apify JavaScript SDK: Actor and storage
• Apify pay-per-event documentation
• Version 0.1.1 was verified in Apify with three results and persistent history when age filtering was disabled. Version 0.1.2 makes that the default; see CHANGELOG.md. The new package still requires deployment.
• Live public-page structure was inspected on 2026-09-21. Test evidence is included in examples/live-verification.json and TEST_REPORT.md.

Independent tool; not affiliated with YouTube or Google.