Video Key Moments: Clip and SeekToAction Markup That Shows

Video key moments are the labeled timestamps Google sometimes shows under a video result, letting a searcher jump straight to the part they care about. You can influence them in three ways: hand-written Clip markup, SeekToAction markup that lets Google work out the segments itself, or chapters in a YouTube description. None of the three is a switch that guarantees the feature. They are inputs, and Google decides whether a given video on a given query earns the display.

That gap between "implemented correctly" and "actually shows" is where most of the frustration lives. This post covers what each method does, how to write the markup, which one fits which situation, and a practical checklist for the common reasons key moments refuse to appear even when the Rich Results Test says everything is fine.

What Key Moments Actually Are

A key moment is a segment of a video with a short label and a start time. In search results it appears as a row of clickable timestamps beneath the video snippet, and clicking one opens the video at that point. The aim is to save the searcher from scrubbing through a twenty-minute tutorial to find the one step they searched for.

It helps to separate two things that get conflated. The first is the feature: timestamped segments shown in search. The second is the markup: structured data you add to tell Google where the segments are. Google can produce the feature without any markup at all, by analysing the video itself and, for YouTube, by reading chapters and transcripts. Markup is an aid that makes your intent explicit, not a precondition.

That matters because it reframes the question. You are not trying to unlock key moments; you are trying to make it easy and unambiguous for Google to segment your video, and then hoping the query and the page deserve the treatment. Keeping that distinction in mind stops you from chasing validator errors when the real issue sits elsewhere.

Three Routes to Key Moments

Each route suits a different kind of video and a different amount of control. Picking the right one up front saves a lot of rework.

The routes differ mainly in who decides where the segments start and what they are called.

• Clip markup: you list each segment yourself, with a name, a start offset in seconds and a URL that opens the video at that moment. You control the labels and the boundaries. It is the most work and the most predictable.
• SeekToAction markup: you do not list segments. You tell Google how your player accepts a timestamp in a URL, and Google identifies the segments automatically and builds the deep links itself. Less work per video, but you give up control of labels.
• YouTube chapters: for videos hosted on YouTube, timestamps in the description (or set through the chapter tools) divide the video into named sections that YouTube and Google can reuse. No schema is needed on your own site for this one.

Clip Markup: You Write the Segments

Clip is a schema.org type that lives inside a VideoObject. Each Clip describes one segment, and you attach several through the hasPart property. The properties Google looks at are the clip's name, its startOffset in seconds from the beginning of the video, and a url that loads the video already positioned at that second. An endOffset is commonly included too so the segment has a defined length.

A worked example makes the shape clear. Imagine a ten-minute video on changing a bicycle tire. Your VideoObject carries the usual name, description, thumbnailUrl, uploadDate and contentUrl or embedUrl. Inside it, hasPart contains three Clip objects: one named "Remove the wheel" starting at 45, one named "Replace the inner tube" starting at 180, and one named "Refit and inflate" starting at 420. Each clip's url is the page address with a timestamp parameter, for example the watch page address followed by ?t=180.

Two details trip people up. First, the url must genuinely land the viewer at that moment. If your player ignores the timestamp parameter and always starts from zero, the markup is technically valid but describes something that does not happen, and it is a good reason for Google to ignore it. Second, the names should describe the content of the segment the way a person would search for it, not be generic labels such as "Part 2".

Use Clip when the video is one you control end to end, when you know the segments in advance, and when the labels matter for how you want the result to read. Training videos, recorded webinars, product walkthroughs and recipe videos are natural fits because their structure is deliberate.

SeekToAction Markup: Google Finds the Segments

SeekToAction takes the opposite approach. Instead of describing segments, you describe the mechanism for jumping to any second of the video. In the VideoObject you add a potentialAction of type SeekToAction. It has a target, which is a URL template containing a placeholder for the seconds value, and a startOffset-input declaring that placeholder as required under a name such as seek_to_second_number.

For the bicycle video the target might be the watch page address with ?t={seek_to_second_number} at the end. Google then fills the placeholder with whatever second it has chosen for each segment and uses the resulting address for the link. You never say where the segments are, which is both the convenience and the risk: the boundaries and labels come from Google's own analysis, so you cannot steer them.

There is a real prerequisite here that the simple-sounding markup hides. For Google to analyse the video, it needs access to the actual video file. That usually means a contentUrl that Googlebot can fetch, rather than an embed that points only at a third-party player page. If the file is blocked by robots.txt, sits behind a login, or is only reachable through a streaming protocol Google cannot read, the automatic route has nothing to work with.

SeekToAction is the pragmatic choice for a large library where writing segment lists by hand is unrealistic, provided the files are fetchable and your player honours the timestamp parameter. If you have only a handful of high-value videos, Clip usually gives a better result for the effort.

YouTube Chapters: The Route With No Schema

If your videos live on YouTube, chapters are the simplest way to give Google labeled segments. You add a list of timestamps with titles to the video description. The conventions are strict enough to be worth stating plainly: the first timestamp must be 0:00, there must be at least three timestamps, they must be in ascending order, and each chapter must be at least ten seconds long. Break any of these and YouTube treats the list as plain text, not chapters.

The titles are the part people underinvest in. "Intro", "Part 1" and "Conclusion" tell a searcher nothing. "Why tire levers scratch rims" or "Checking the valve stem" read like the thing someone typed into a search box, and Google can surface them as labels.

Chapters work on the YouTube watch page and feed YouTube's own player and search. Whether Google Search then shows them as key moments for a given result is, again, Google's call. Importantly, chapters on YouTube do nothing for a copy of the same video embedded on your own site, which is a separate page with its own indexing story.

Many sites end up doing both: YouTube chapters for the YouTube listing, and VideoObject markup with Clip or SeekToAction on their own page that embeds the video. These do not conflict, but they should agree. If the YouTube chapters call a segment one thing and your Clip markup calls it something different, you are sending mixed signals for no benefit.

Why Key Moments Often Do Not Appear

This is the section most guides skip. When you have valid markup and still see nothing, the cause is rarely the syntax. Work through these in order, because the early ones are the most common.

Then keep in mind that several of these are conditions you can fix, and one of them is simply the nature of the feature.

• The video is not the page's main content. Google indexes a video for video features when it is a prominent, central element of a watch-style page. A video buried in the footer of an article, or one of twelve on a listing page, is often not treated as the page's video at all.
• The page or video is not indexed. Markup on a URL that Google has not indexed cannot produce anything. Check the URL in Search Console first, and look at the video indexing report to see whether the video was detected and why others were not.
• The file or thumbnail cannot be fetched. A blocked contentUrl, an expired signed link, or a thumbnail that returns an error all undermine the video as a whole, not just its segments.
• Timestamps do not work. If the URL you give for a clip or template does not actually start playback at that second, the segments are not usable and cannot be shown honestly.
• Markup and page disagree. Structured data must describe what a visitor sees. A clip named for a section that is not in the video, or a description that does not match, counts against trust in the markup.
• The query does not call for it. Key moments tend to appear where a searcher is looking for a specific step or answer inside a longer video. For a navigational or very broad query, Google has little reason to show segments even on a perfect page.
• The video is short. A video of under a minute or two has little internal structure to segment, so the feature offers no value and is rarely used.
• It is simply not guaranteed. Google documents structured data as eligibility for a feature, not a promise. Two equally well-marked-up videos can be treated differently.

Testing the Markup Without Fooling Yourself

Start with the Rich Results Test or the Schema Markup Validator to confirm the JSON-LD parses and that the VideoObject has its required properties. A clean result there proves only that the syntax is acceptable. It says nothing about whether Google will display key moments, and treating a green tick as success is the most common testing mistake.

Next, do the checks the validators cannot. Open each clip URL or the filled-in template by hand, substituting a real number of seconds, and confirm the video really starts there. Fetch the contentUrl from outside your network to confirm it is reachable without cookies. Use the URL Inspection tool to see the rendered HTML Google received, because video markup injected late by JavaScript is sometimes missed.

Then watch Search Console. The video indexing report lists pages where a video was found and explains why other pages had no indexed video, with reasons such as the video not being the main content or the file being unreachable. It is the nearest thing to a diagnostic for this whole area. Give Google time after a fix: recrawling and reprocessing video can take days, and there is no button that forces a display.

Finally, test the way a searcher would. Search for a phrase that matches a specific step in your video, not the video's title. Key moments are a response to specificity, so a query that matches the whole video will often show a plain result.

Choosing a Method and Avoiding Common Mistakes

For a small set of important videos on your own domain, write Clip markup with carefully worded names, and make sure the clip URLs genuinely seek. For a big catalogue with fetchable video files, SeekToAction is the scalable option. For anything hosted on YouTube, add proper chapters regardless, because they cost nothing and serve the platform where much video discovery happens.

A few mistakes show up repeatedly. Marking up clips for a video that has been replaced with a new edit leaves stale offsets pointing at the wrong scenes. Copying the same generic clip names across every video makes the labels worthless. Adding both Clip and SeekToAction to the same video is unnecessary confusion when one clear method would do. And inventing segments that the video does not contain, just to fill the markup, risks the page being treated as misleading structured data.

The underlying principle is that the markup should be a truthful map of the video. If the map is accurate, easy to read and backed by a video that is reachable and central to its page, you have done everything within your control. The rest is Google's decision about the query in front of it.