Video key moment links open at the wrong timestamp
Test SeekToAction URL templates against your player, preserve timestamp parameters through redirects, and verify that video deep links reach the intended moment.
By Crawlito · 5 min read
In short
- SeekToAction describes a timestamp URL pattern; it does not implement seeking in the player.
- The URL template and player must agree on the timestamp parameter and units.
- Test direct timestamp links after redirects and after the video is ready.
On this page
- Test a concrete timestamp URL first
- Compare the schema template with the player contract
- Trace redirects and route handling
- Apply the offset when the player is ready
- Verify the markup and the reader experience together
- Choose Clip when you are publishing explicit chapters
- Keep timestamp links stable through releases
- Frequently asked questions
If a video key moment link opens at the beginning instead of the intended timestamp, test the actual URL with your player before changing schema. SeekToAction describes how a timestamp fits into a URL; the player still needs to read that value and seek correctly. Verify parameter preservation, units, and player readiness on a direct page load.
A valid structured-data object can point to a nonfunctional deep link. The repair should prove that a reader who opens the link reaches the intended part of the video.
Test a concrete timestamp URL first
Choose a video you control and a point well inside its duration. Open a URL such as:
https://www.example.com/watch/setup?t=90The example assumes that your player uses t as a seconds parameter. Use the actual supported format for your implementation.
Watch the player state after the media is ready. Confirm that the displayed or playback position reaches the intended point. If autoplay is restricted, test where playback begins when the user presses play rather than treating the absence of autoplay as a seeking failure.
Try another timestamp and a fresh browser session. A player may remember the last position and make one test appear successful by coincidence.
Record the original URL, final URL, selected video, requested offset, and observed position. That compact record is enough to separate a broken link format from a general video indexing problem.
The video watch-page guide covers access and page suitability when the video itself is not discoverable.
Compare the schema template with the player contract
Google's video structured-data documentation describes SeekToAction as a way to communicate the timestamp URL structure. It requires the target and matching startOffset-input relationship for this purpose.
A simplified fragment nested in a VideoObject can be:
{
"potentialAction": {
"@type": "SeekToAction",
"target": "https://www.example.com/watch/setup?t={seek_to_second_number}",
"startOffset-input": "required name=seek_to_second_number"
}
}This is a relationship fragment, not a complete VideoObject example. The surrounding object still needs accurate properties for the actual video and the current documented requirements.
Compare the parameter name with the player implementation. A template using t does not work if the player reads start. Also compare units: a player expecting milliseconds needs a deliberate conversion if the published contract uses seconds.
Do not guess the format based on another video platform. The URL must work on the page where your own video is presented.
Trace redirects and route handling
Fetch the timestamp URL and inspect the redirect sequence:
curl -sS -L -D video-headers.txt -o video-page.html \
-w '%{url_effective}\n' \
'https://www.example.com/watch/setup?t=90'Check whether the final URL preserves the intended parameter. A host normalization, trailing-slash redirect, or old-slug mapping can accidentally discard it.
Curl does not run the player, so this verifies the URL path rather than the final playback state. Follow it with the browser test.
If the app changes the URL after load, inspect that route transition too. A cleanup routine may remove parameters before the player reads them.
The URL parameter guide helps distinguish content selection from tracking values. A video timestamp can be meaningful to the reader even when the page uses a single canonical watch URL.
Do not strip all query parameters as a generic SEO cleanup if some implement a useful deep link.
Apply the offset when the player is ready
Find the code or player integration that reads the timestamp. Confirm that it validates the value, selects the right video, and applies the offset at a supported point in the media lifecycle.
A seek attempted before the player has enough information may fail or be overwritten during initialization. A later resume-position feature can also replace the requested timestamp.
Define precedence for the user journey. When someone opens an explicit timestamp link, decide how that interacts with a saved viewing position. Test the decision rather than allowing whichever callback runs last to determine the result.
Handle invalid values predictably. Negative, nonnumeric, or out-of-range offsets should not break the page or select an unrelated video. Use the player library's documented behavior for the supported implementation.
Do not expose a generic script that accepts arbitrary URLs from query parameters to fix the issue. The deep link should select a known video and a bounded position within that video's supported player flow.
Verify the markup and the reader experience together
After the repair, inspect the public page's structured data and open concrete URLs generated from its target pattern. Use several offsets within the video.
Check a direct visit, navigation from another page, and a return from an old URL redirect. These paths may initialize the player differently.
A useful matrix is:
| Case | Expected result |
|---|---|
| No timestamp | Normal starting behavior |
| Valid middle offset | Intended moment after player readiness |
| Second valid offset | Different correct moment |
| Invalid value | Safe defined fallback |
| Old URL with timestamp | Correct video and preserved meaningful offset |
Use the JSON-LD error guide for syntax checks, but keep the browser playback test as a separate acceptance criterion.
A schema validator cannot prove that the JavaScript player honors the URL. Conversely, a working timestamp link does not establish that every structured-data field is correct. Both tests matter.
Choose Clip when you are publishing explicit chapters
Google also documents Clip for explicitly described segments. SeekToAction and Clip serve different authoring needs: one describes a URL pattern for automatically identified moments, while the other supplies particular segments.
If your editorial team maintains chapter labels and boundaries, review the appropriate documented approach instead of forcing all information into a generic timestamp template.
Keep chapter names meaningful and match them to the actual video. A chapter link labeled “Import the file” should not jump to an introduction or a different product version.
When a video is replaced, review its offsets. The old timestamps may remain valid numbers while pointing to the wrong explanation in the new recording.
Do not promise that adding either type produces key moments in Search. The immediate result you can verify is accurate markup and a functioning reader journey.
Keep timestamp links stable through releases
Include a few known timestamp URLs in the release sample when changing the router, player, consent flow, or video host. These are the components most likely to break the path.
A consent gate can delay player initialization. Verify that the requested offset survives the approved interaction and is applied when the video becomes available. Do not bypass the gate simply to make an automated test pass.
Check mobile behavior too, especially if the player changes implementation or enters a different viewing mode. The same URL should preserve its intended meaning across supported experiences.
Record the video identifier and tested offsets with the release evidence. A screenshot of the page without a player position cannot establish that deep linking works.
For an agency handoff, describe the defect precisely: the redirect dropped the timestamp, or the player reset it after initialization. That points to a concrete owner and avoids an unfocused request to “fix video SEO.”
Frequently asked questions
Does SeekToAction make the player support timestamps?
No. It describes the URL pattern. The player and page code must implement the corresponding behavior.
Should every timestamp URL have a separate article?
Not merely to support seeking. Treat the watch page and its navigation behavior according to the actual content structure.
Does no autoplay mean the timestamp failed?
Not necessarily. Verify the selected position and where playback begins after the permitted user action.
Use the free Crawlito check on the watch page after verifying its timestamp links in the browser.
Filed under Structure and schema. Topics: structured-data, video, javascript