Speculation Rules Auditor

Audit a public web page for Speculation Rules API usage in one API call. Detects inline <script type="speculationrules"> blocks and the Speculation-Rules HTTP response header, parses each prefetch/prerender rule, validates JSON syntax and rule shapes, flags broad matchers without exclusions, and returns a readiness score, letter grade, and Core Web Vitals recommendations. Built for performance engineers, SEO teams, and site migration QA.

Use cases

• Performance engineers - verify prefetch and prerender rules are present, valid, and correctly scoped before launches
• SEO teams - confirm Speculation Rules survive CMS template changes and migrations
• Site migration QA - catch missing or malformed speculation rules when moving between frameworks, CDNs, or edge providers
• Frontend platform teams - monitor for broad href_matches: /* rules without exclusions that risk wasted prerenders and side-effecting GETs
• Agency consultants - batch-audit client pages and return structured recommendations

Input

Field	Type	Required	Default	Description
startUrl	string	yes	-	Public page URL to audit
timeoutSeconds	integer	no	10	Per-request timeout (3-30 seconds)
maxHtmlBytes	integer	no	1048576	Maximum HTML body size to download and parse (16 KB - 2 MB)

Example input

{
  "startUrl": "https://example.com",
  "timeoutSeconds": 10,
  "maxHtmlBytes": 1048576
}

Output

A single dataset item with the full audit:

Field	Type	Description
inputUrl	string	The URL provided as input
finalUrl	string	Final URL after redirects
https	boolean	Whether the final response was served over HTTPS
inlineRuleCount	integer	Number of inline <script type="speculationrules"> blocks found
speculationRulesHeader	string | null	Value of the Speculation-Rules HTTP response header, or null when absent
headerRuleUrls	array	URLs referenced by the Speculation-Rules header (resolved against the page), empty when header absent
byAction	object	Count of rules grouped by action (prefetch, prerender)
eagernessLevels	array	Distinct eagerness values used across rules (immediate, eager, moderate, conservative)
totalRules	integer	Total number of prefetch and prerender rule entries parsed
ruleBlocks	array	Per-block analysis (see below)
issues	array	Aggregated issue descriptions across all rule blocks
score	integer	Speculation rules readiness score (0-100)
grade	string	Letter grade (A+, A, B, C, D, E, F)
checkedAt	string	ISO 8601 timestamp
recommendations	array	Actionable recommendations for improving Speculation Rules API readiness

ruleBlocks array

Each entry is one inline block or one header reference:

Field	Type	Description
source	string	inline for <script type="speculationrules"> blocks, header for Speculation-Rules header references
parseError	string | null	JSON parse error message, or null when the block parsed successfully
actionsFound	array	Actions present in the block (prefetch, prerender)
ruleCount	integer	Number of rule entries in the block
rules	array	Per-rule analysis (see below) for inline blocks
issues	array	Issue descriptions for this block
urls	array	For header blocks, the resolved rule-file URLs
urlCount	integer	For header blocks, the number of resolved URLs

rules array (within inline ruleBlocks)

Each entry describes one prefetch or prerender rule:

Field	Type	Description
action	string	prefetch or prerender
hasUrls	boolean	Whether the rule has a urls array
hasWhere	boolean	Whether the rule has a where predicate
urlsCount	integer	Number of distinct non-empty URLs in urls
wherePredicate	string | null	Recognized predicate in where (href_matches, selector_matches, and, not), or null
eagerness	string | null	Eagerness value (immediate, eager, moderate, conservative)
defaultEagernessApplied	boolean	True when eagerness was defaulted because the rule omitted it
issues	array	Issue descriptions for this rule

Rules checked

The Speculation Rules API uses JSON objects inside <script type="speculationrules"> blocks or files referenced by the Speculation-Rules HTTP response header:

{
  "prefetch": [{ "urls": ["/next"], "eagerness": "eager" }],
  "prerender": [{ "where": { "href_matches": "/*", "not": { "href_matches": "/logout" } }, "eagerness": "moderate" }]
}

This actor parses each block and flags:

• Malformed JSON (browsers silently ignore unparseable blocks)
• Rules with neither urls nor where
• Rules with both urls and where (spec: urls should be exclusive)
• urls arrays that are not arrays, empty, contain non-strings, empty strings, or duplicates
• where objects with no recognized predicate
• Broad href_matches: /* or * matchers without a not exclusion for state-changing paths (e.g., /logout)
• Prerender with immediate or eager eagerness and more than 3 URLs (exceeds Chrome's recommended 1-2 immediate prerenders)
• Prerender with aggressive eagerness on broad matchers without exclusions
• Invalid eagerness values

Grading scale

Score range	Grade
95-100	A+
85-94	A
75-84	B
65-74	C
50-64	D
30-49	E
0-29	F

Scoring rewards genuine adoption (inline blocks, header references, prefetch, prerender, and a graduated prefetch-plus-prerender strategy), then subtracts penalties for each issue. An empty page (no rules and no header) scores 0 because Speculation Rules are opt-in, not a defect.

Example output

{
  "inputUrl": "https://example.com",
  "finalUrl": "https://example.com/",
  "https": true,
  "inlineRuleCount": 1,
  "speculationRulesHeader": null,
  "headerRuleUrls": [],
  "byAction": { "prefetch": 1, "prerender": 1 },
  "eagernessLevels": ["eager", "moderate"],
  "totalRules": 2,
  "ruleBlocks": [
    {
      "source": "inline",
      "parseError": null,
      "actionsFound": ["prefetch", "prerender"],
      "ruleCount": 2,
      "rules": [
        { "action": "prefetch", "hasUrls": true, "hasWhere": false, "urlsCount": 2, "wherePredicate": null, "eagerness": "eager", "defaultEagernessApplied": false, "issues": [] },
        { "action": "prerender", "hasUrls": false, "hasWhere": true, "urlsCount": 0, "wherePredicate": "and", "eagerness": "moderate", "defaultEagernessApplied": false, "issues": [] }
      ],
      "issues": []
    }
  ],
  "issues": [],
  "score": 100,
  "grade": "A+",
  "checkedAt": "2026-08-14T12:00:00.000Z",
  "recommendations": [
    "Combine an eager prefetch of common next pages with a moderate prerender for the rest, so prefetches warm before hover-triggered prerenders.",
    "Speculation Rules look well-configured. Schedule this audit periodically to catch CMS template regressions and rule-rot."
  ]
}

Security

• Only public HTTP/HTTPS URLs are accepted
• SSRF protection: localhost, private IPv4/IPv6, and DNS-resolving-to-private IPs are blocked
• URLs with embedded credentials are rejected
• Redirects are manually revalidated before following (max 3)
• HTML body is capped at maxHtmlBytes to prevent oversized responses
• The actor does not fetch the URLs referenced by the Speculation-Rules header; it only reports them
• No browser automation, no proxies, no cookies stored

Pricing

Pay per event:

Event	Price
Actor start	$0.005
Page audited	$0.01

A single-page audit costs approximately $0.015.

FAQ

What is the Speculation Rules API? The Speculation Rules API lets pages hint to the browser which future navigations to prefetch or prerender. Rules are JSON objects inside inline <script type="speculationrules"> elements or external files referenced by the Speculation-Rules HTTP response header. Each rule targets a urls list or a where predicate (with href_matches or selector_matches) and an eagerness level (immediate, eager, moderate, conservative).

How is this different from a resource hints auditor? A resource hints auditor inspects <link rel="preload">, preconnect, prefetch, dns-prefetch, and modulepreload tags. This actor focuses exclusively on the newer Speculation Rules API, which targets document navigations (not individual resource fetches) and uses a JSON rule structure with eagerness levels and where predicates. The two are complementary, not overlapping.

Does the actor fetch the external rule file referenced by the Speculation-Rules header? No. The actor reports the header value and resolves the referenced URLs against the page, but it does not download the external rule file. Fetching user-controlled secondary URLs would add another SSRF surface for marginal value; the inline block analysis already covers the common deployment.

Can I audit multiple pages in one run? This actor audits one page per run. For bulk audits, schedule multiple runs.

Does the actor follow redirects? Yes, up to 3 redirects. Each redirect target is revalidated for SSRF safety before it is followed.