# Speculation Rules API

Category: [Performance & Core Web Vitals](https://seo-geo-glossary.com/en/glossary/category/performance-core-web-vitals/) › [Optimization](https://seo-geo-glossary.com/en/glossary/category/performance-core-web-vitals/optimization/)

The **Speculation Rules API** lets a web page tell the browser which URLs a visitor will probably open next. The browser then prefetches those pages or prerenders them in a hidden tab, so the navigation feels instant.

## How does it work?
Rules are written as JSON inside a `<script type="speculationrules">` element, or in a file referenced by the `Speculation-Rules` HTTP header. MDN says the API supersedes the deprecated `<link rel="prerender">`.

- **Prefetch** downloads only the response body of the page, without subresources. It is cheap.
- **Prerender** fetches and renders the whole page, including JavaScript, in an invisible tab. MDN compares the cost to rendering an iframe and advises using it sparingly.
- **Eagerness** controls when speculation starts. Chrome documents `immediate` (as soon as the rules are observed), `eager` (after a very short hover of 10 ms on desktop), `moderate` (after a 200 ms hover on desktop) and `conservative` (on pointer or touch down). Mobile uses viewport heuristics for `eager` and `moderate`.
- **Document rules** use patterns such as `href_matches` instead of fixed URL lists.

## Example
```html
<script type="speculationrules">
{
  "prerender": [{
    "where": { "and": [
      { "href_matches": "/*" },
      { "not": { "href_matches": "/logout" } }
    ]},
    "eagerness": "moderate"
  }]
}
</script>
```

## Common mistakes
Prerendered pages run their JavaScript before the visitor arrives. MDN warns against speculating on URLs with side effects, such as logout or add-to-cart, and recommends delaying analytics and ad code with `document.prerendering`. Servers can recognize speculative requests by the `Sec-Purpose` header.

## Related terms

- [Back/forward cache](https://seo-geo-glossary.com/en/glossary/back-forward-cache/index.md)
- [Largest Contentful Paint (LCP)](https://seo-geo-glossary.com/en/glossary/largest-contentful-paint/index.md)
- [Core Web Vitals](https://seo-geo-glossary.com/en/glossary/core-web-vitals/index.md)
- [Google cache](https://seo-geo-glossary.com/en/glossary/google-cache/index.md)
- [Preload / preconnect](https://seo-geo-glossary.com/en/glossary/preload-preconnect/index.md)

## Sources

- [Speculation Rules API – MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API)
- [Guide to implementing speculation rules for more complex sites – Chrome for Developers](https://developer.chrome.com/docs/web-platform/implementing-speculation-rules)
- [Speculative loading – WHATWG HTML Standard](https://html.spec.whatwg.org/multipage/speculative-loading.html)

---

Last updated: October 7, 2026
URL: https://seo-geo-glossary.com/en/glossary/speculation-rules-api/