How do I add key moments to a video with structured data?

Definition: Video key moments are links to specific segments of a video in Google Search. As of October 2026, Google supports structured data, a format that describes page content for machines, using Clip for publisher-defined segments and SeekToAction for URL templates used with automatically identified segments.

Key facts

• Google's video structured data documentation requires a video lasting at least 30 seconds, on a page where visitors can watch it, with URLs that support jumping into playback.
• Schema.org's Clip definition expresses startOffset and endOffset as seconds from the beginning of the work.
• Schema.org defines SeekToAction as an action for reaching a specific startOffset timestamp within a VideoObject, typically through a URL template.

What must work before adding the markup?

A VideoObject is the structured data object describing the video. Google's shared guidelines for key moments require it on a page where the video is watchable. Its required properties are name, thumbnailUrl and uploadDate.

The video URL must support a deep link, meaning a link that starts playback at a specific point. Google's example, https://www.example.com/example?t=30, starts playback 30 seconds into the video. For Clip, the segment URL must use the same URL path as the video, with additional query parameters specifying the time. The player must actually honor the timestamp; checking playback is therefore part of implementation.

How does Clip specify individual segments?

Google's Clip property table requires a descriptive name, a numeric startOffset and a url pointing to the segment's start. endOffset is recommended. Segments belong inside the parent video's hasPart property, and clips on the same page for the same video must have distinct start times.

This JSON-LD example, adapted from Google's cat video example, includes the required video fields and a segment beginning at 30 seconds and ending at 45 seconds. JSON-LD expresses structured data as JSON inside a script element. The example values require replacement with the actual video's details and working URLs.

<script type="application/ld+json">
{
  "@context": "https://schema.org/",
  "@type": "VideoObject",
  "name": "Cat video",
  "uploadDate": "2024-07-19T08:00:00+08:00",
  "thumbnailUrl": "https://www.example.com/cat.jpg",
  "contentUrl": "https://www.example.com/cat_video_full.mp4",
  "hasPart": [{
    "@type": "Clip",
    "name": "Cat jumps",
    "startOffset": 30,
    "endOffset": 45,
    "url": "https://www.example.com/example?t=30"
  }]
}
</script>

How does SeekToAction describe timestamp URLs?

Google's SeekToAction instructions describe a potentialAction nested in the VideoObject. Google uses this template to link to moments it identifies automatically. The following fragment belongs inside an existing video object containing the required video properties:

{
  "potentialAction": {
    "@type": "SeekToAction",
    "target": "https://video.example.com/watch/videoID?t={seek_to_second_number}",
    "startOffset-input": "required name=seek_to_second_number"
  }
}

The target is the page URL containing the video, with {seek_to_second_number} replacing the timestamp value. The matching startOffset-input tells Google where to supply the number of seconds. The page URL requires adaptation to the site's working timestamp URL structure. Google also requires access to the video content files for this approach.

How is the implementation checked?

Google's implementation workflow calls for validating the markup with the Rich Results Test and fixing critical errors. After deployment, the URL Inspection tool checks how Google sees the page. Access must be possible without a login or blocking indexing directives.

A playback check complements markup validation: opening each Clip.url, or a concrete timestamp URL generated from target, checks whether the video begins at the intended point.

Related terms

• Structured data
• JSON-LD
• What thumbnail data does Google require for VideoObject markup?
• How do I test a URL or code snippet with Google's Rich Results Test?

FAQ

Can I choose the segment labels myself?

Yes. Google's key moments guidance describes Clip as the option for specifying segment boundaries and labels. Google says it prioritizes key moments supplied through structured data or the YouTube description.

Can I use these methods for an English video?

Yes. The same documentation supports Clip in all languages where Google Search is available, and lists English among the supported languages for SeekToAction.

What if my video is hosted on YouTube?

You can provide timestamps and labels in the YouTube description. Google's guidance places each timestamp and its label on the same line, with timestamps in chronological order and each on a new line.

Sources

1. Google Search Central, "Video (VideoObject, Clip, BroadcastEvent) structured data", 24 September 2026
2. Schema.org, "Clip", undated
3. Schema.org, "SeekToAction", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer