PageSpeed Insights

Google PageSpeed Insights — the API behind pagespeed.web.dev.

Get started: https://developers.google.com/speed/docs/insights/v5/get-started Reference: https://developers.google.com/speed/docs/insights/v5/reference/pagespeedapi/runpagespeed

Auth

A Google Cloud API key, created under APIs & Services → Credentials on a project that has the PageSpeed Insights API enabled. The API is free — no billing account is required.

The key is sent in the x-goog-api-key header. Google's own examples append ?key=… to the URL; both were probed and work, and the header is used so the key never appears in a URL.

Actions

All four call the same endpoint — GET /pagespeedonline/v5/runPagespeed — and differ only in the slice of the response they return. The raw response is several hundred kilobytes of Lighthouse JSON, which is why no action returns it unless asked.

| Action | Returns | |---|---| | Get Performance Score | Category scores out of 100 plus the lab metrics, shaped for a threshold check | | Analyze URL | The same summary, with an opt-in fullReport carrying the raw Lighthouse JSON | | Get Improvement Opportunities | Every failed audit, sorted by estimated milliseconds saved | | Get Core Web Vitals (Field Data) | Chrome UX Report data for the page and its origin |

Triggers

None. PageSpeed Insights has no webhooks and no event stream, so there is nothing to poll for. Scheduled monitoring is a Schedule trigger followed by Get Performance Score.

Notes

• A run is a live Lighthouse analysis and takes roughly 10–60 seconds per URL.
• Field data only exists for pages with enough real Chrome traffic. hasPageFieldData and hasOriginFieldData say whether there was any, so an empty result is not mistaken for a healthy one.
• Google validates the API key before it validates parameters, so the connection check sends a deliberately parameter-less request: it proves the key without starting a Lighthouse run or spending quota.