YouTube Title & Thumbnail Change Tracker

Every other YouTube actor tells you what a video looks like now. This one tells you what changed. Give it a list of channels, playlists or individual videos, run it on a schedule, and each run returns only the metadata edits it has seen since the previous run: a title rewritten, a description edited, a thumbnail swapped, tags added or removed, the category changed, or the video gone private, unlisted or deleted. Every event carries the before value, the after value, and the view/like/comment counts at the moment the edit was spotted — so when a competitor re-titles a video on day three and it suddenly takes off, you have the old title, the new title, and the view count it was sitting at when they made the call.

It uses the official YouTube Data API v3 with your own free API key. Checking 500 videos costs about 12 units of the free 10,000-unit daily quota, so quota is not a practical limit.

What a run looks like

• First run on a video — nothing to compare against, so the actor records the current metadata and returns one baseline record per video, showing what it will be watching from now on. No change events, and none charged.
• Every run after that — only the edits. A watchlist where nothing was touched returns an empty dataset, and that is the correct answer, not a failure.

Input

Field	Type	Default	Notes
apiKey	string (secret)	—	Required. Your own YouTube Data API v3 key. See below.
channelUrls	array of strings	["https://www.youtube.com/@MrBeast"]	Channel URLs, @handles, or raw UC... IDs. Tracks each channel's most recent uploads.
videoUrls	array of strings	[]	Specific videos: watch/shorts/embed/youtu.be URLs, or bare 11-character IDs.
playlistUrls	array of strings	[]	Playlist URLs or raw PL... IDs.
maxVideosPerSource	integer	10	Videos taken from each channel or playlist, newest first. Max 500.
maxVideosPerRun	integer	50	Hard cap on videos checked per run, across all sources. Max 2000.
trackedFields	array	all six	Any of title, description, thumbnail, tags, category, status.
thumbnailCheckMode	headers | bytes	headers	See "How thumbnail detection works".
maxChangeEvents	integer	500	Cap on change events returned and charged per run.
markGoneAfterMisses	integer	2	Consecutive runs a video must be missing before a gone event fires. 1–10.
includeBaselineRecords	boolean	true	Emit a baseline record the first time each video is seen.
forceBaseline	boolean	false	Discard remembered state and re-baseline everything. Leave off for scheduled runs.
stateKeyValueStoreName	string	youtube-metadata-tracker-state	Named key-value store holding last-seen metadata. Change it to run two independent watchlists.
requestTimeoutSecs	integer	30	5–120.
maxRequestRetries	integer	3	0–10.
proxyConfiguration	object	no proxy	Rarely needed — Google's API and image CDN do not IP-block.

At least one of channelUrls, videoUrls or playlistUrls must be non-empty.

Getting an API key (about two minutes, free)

1. Open console.cloud.google.com/apis/credentials.
2. Create Credentials → API key, and copy it.
3. In API Library, find YouTube Data API v3 and click Enable for the same project.
4. Paste the key into apiKey.

No OAuth, no login, no billing account.

Output

One record per change event. changeType is one of baseline, title, description, thumbnail, tags, category, status or gone.

Field	Type	Notes
changeType	string	Which field changed.
videoId, videoUrl, videoTitle	string	The video. videoTitle is the current title (last known, for gone).
channelId, channelTitle, channelUrl	string	The channel.
publishedAt	string	ISO 8601 original publish time.
previousValue, newValue	string | null	Before and after. For tags, comma-joined. For category, the readable name. For thumbnail, the image fingerprint.
addedWords, removedWords	string[]	Word-level title diff. Empty for other change types.
titleDiff	string | null	Inline title diff, e.g. (Official [-Music-] Video) {+(4K Remaster)+}.
addedTags, removedTags	string[]	Tags gained and lost.
categoryName	string | null	Current category, readable.
privacyStatus	string | null	public, unlisted, or gone.
thumbnailUrl	string	Canonical i.ytimg.com thumbnail path.
viewCount, likeCount, commentCount	number | null	Counts at the moment the edit was observed. null when the creator hides them.
previousObservedAt, observedAt	string	ISO 8601. The edit happened somewhere between these two timestamps.

A real title record, from the test run in TEST-REPORT.md:

{
  "changeType": "title",
  "videoId": "dQw4w9WgXcQ",
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "videoTitle": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "channelTitle": "Rick Astley",
  "channelUrl": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
  "publishedAt": "2009-10-25T06:57:33Z",
  "previousValue": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
  "newValue": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "addedWords": ["(4K", "Remaster)"],
  "removedWords": ["Music"],
  "titleDiff": "Rick Astley - Never Gonna Give You Up (Official [-Music-] Video) {+(4K Remaster)+}",
  "addedTags": [],
  "removedTags": [],
  "categoryName": "Music",
  "privacyStatus": "public",
  "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
  "viewCount": 1808453650,
  "likeCount": 19353634,
  "commentCount": 2455561,
  "previousObservedAt": "2026-08-26T23:27:03.367Z",
  "observedAt": "2026-08-26T23:27:19.656Z"
}

How thumbnail detection works

When a creator replaces a thumbnail, the URL does not change — i.ytimg.com/vi/{videoId}/hqdefault.jpg is the same path before and after. Comparing thumbnail URLs, which is what a snapshot scraper gives you, will never detect a swap. This actor compares the image itself:

• headers (default) — a HEAD request to the CDN, comparing the ETag and byte length. The ETag is derived from the image version, so it changes when the picture does. Near-zero bandwidth, one cheap request per video.
• bytes — downloads the JPEG and compares a SHA-256 of the actual bytes. Immune to any CDN quirk, but roughly 20 KB per video per run.

Switching modes re-baselines the thumbnail rather than reporting a false change.

Cost

Two events: video-checked ($0.0005) for each video polled and compared, and change-detected ($0.012) for each metadata edit reported. Full reasoning in MONETIZATION.md.

Scenario	Cost
Default run: 1 channel, 10 videos, first (baseline) run	$0.005
Same watchlist, a normal day with no edits	$0.005
Same watchlist, a day with 2 edits	$0.029
100-video watchlist, daily, ~3 edits/day	$0.086/day, about $2.58/month
500-video watchlist, daily, ~10 edits/day	$0.37/day, about $11.10/month

Because most videos are never edited, the recurring cost is dominated by video-checked, which is the cheap event by design. Set maxVideosPerRun and maxChangeEvents to put a hard ceiling on any single run, and set a total budget with the Apify Max total charge setting — the actor reads it, stops cleanly when it is reached, and delivers everything it has already charged you for.

Known limitations

Read these before you run it on something that matters.

• You need your own YouTube Data API v3 key. Free, no billing account, about two minutes. But it is a real setup step and the actor cannot run without it.
• Nothing is detected on the first run. There is no history to compare against, so run one gets you baseline records only. Real change detection starts on run two.
• Edits are dated to a window, not an instant. The actor knows an edit happened between previousObservedAt and observedAt. Run hourly and that window is an hour; run weekly and it is a week. It cannot recover edits made before you started watching — there is no historical backfill, from this actor or from the YouTube API.
• Private and deleted are indistinguishable. The API silently omits both, identically. You get changeType: "gone" and no way to tell which happened. Unlisted videos are usually still returned by ID, so those normally surface as a status change rather than gone.
• gone is debounced by design. With the default markGoneAfterMisses: 2, a video must be missing on two consecutive runs before it is reported, so a gone event lags real deletion by one run. Set it to 1 for immediate reporting and accept occasional false alarms from API hiccups.
• Thumbnail changes can be reported late. i.ytimg.com is CDN-cached, so a replacement can take minutes to hours to propagate to the edge node the actor hits. Treat observedAt on a thumbnail event as "when we saw it", not "when they changed it".
• tags are only visible on some videos. snippet.tags is returned for many but not all videos, and Google has restricted tag visibility before. Where tags are absent the actor sees an empty list and simply never reports tag changes for that video.
• Deleting the state store resets everything. The watchlist's memory lives in the named key-value store. Delete it, rename it, or set forceBaseline: true, and the next run re-baselines and reports nothing.
• maxVideosPerSource takes the newest uploads, not the most-watched. If a channel posts daily, a value of 10 means you are watching a rolling ten-day window and older videos silently fall out of the watchlist. Raise it, or pin the videos you care about in videoUrls, which always take priority.
• Statistics can be null. Creators can hide like counts and disable comments. The actor reports null rather than pretending the number is zero.
• No transcripts, comments, or revenue data. This actor tracks metadata fields only.

Legal

Not affiliated with, endorsed by, or sponsored by YouTube or Google LLC. YouTube is a trademark of Google LLC.

Metadata comes from the official YouTube Data API v3, using your own API key. That makes you the API client in Google's eyes: the key is registered to your Google Cloud project, the quota is yours, and your use is governed by your own agreement with Google. You are responsible for complying with the YouTube API Services Terms of Service and the YouTube API Services Developer Policies. Points that bear directly on how this actor works:

• Stored API data must be refreshed or deleted. The Developer Policies restrict how long API data (other than resource IDs) may be retained without refreshing — currently 30 days. This actor keeps last-seen titles, descriptions and tags in a key-value store in order to diff them, and a scheduled run refreshes that state every time it runs. If you stop running the actor, delete its state key-value store, and apply the same rule to the change events you export downstream.
• Attribution and branding requirements apply if you display YouTube data in a product or interface.
• Do not use the data to build a service that replicates core YouTube features, and do not use it for the purposes the policies prohibit.

Thumbnail images are fetched directly from YouTube's public image CDN (i.ytimg.com), not through the Data API. The Data API does not expose an image fingerprint, so there is no API-only way to detect a thumbnail swap. This is a plain request for a publicly served image, but it is outside the documented API surface, and YouTube's Terms of Service likely restrict automated access to its properties regardless of whether the content is publicly reachable. Using this actor may therefore not comply with those terms. You are responsible for your own compliance and for how you use the data it returns. If you would rather not make those requests at all, remove thumbnail from trackedFields — every other field is served entirely by the official API.

This actor collects public video and channel metadata only. It does not access private or login-walled content, and it collects no personal data beyond the public channel identifiers and channel titles attached to the videos you choose to watch.