PageSpeed Insights API Guide
The PageSpeed Insights API returns Lighthouse performance data for any URL. Free tier gives you 25,000 requests per day.
What You Get
Every API response includes:
| Data | Description |
|---|---|
| Performance score | 0-100 Lighthouse score |
| Core Web Vitals | LCP, CLS, TBT lab data |
| Field data | Real Chrome user metrics (when available) |
| Opportunities | Specific optimization suggestions |
| Diagnostics | Detailed performance breakdowns |
The response combines lab data (Lighthouse synthetic tests) with field data from the Chrome User Experience Report when enough real user data exists for that URL.
Quick Start
Test any URL with a single curl command:
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://example.com&key=YOUR_API_KEY"
The API returns JSON with everything Lighthouse captures. No authentication beyond the API key.
When to Use the PSI API
Good for:
- Spot-checking individual URLs programmatically
- Integrating performance scores into dashboards
- CI checks on critical landing pages
- Monitoring specific URLs over time
Limitations:
- Single URL per request
- Rate limited (400 requests per 100 seconds)
- No crawling — you must provide URLs
- Lab data only for new/low-traffic URLs
API vs CLI vs Unlighthouse
| Feature | PSI API | Lighthouse CLI | Unlighthouse |
|---|---|---|---|
| URLs per request | 1 | 1 | Entire site |
| Rate limit | 400/100s | None | None |
| Infrastructure | Google servers | Your machine | Your machine |
| Cost | Free (25k/day) | Free | Free CLI |
| Field data | Yes | No | No |
| URL discovery | Manual | Manual | Automatic crawl |
The PSI API is useful when you need field data or want to avoid running Lighthouse locally. For site-wide testing, the single-URL limitation becomes impractical.
Response Structure
Key paths in the JSON response:
lighthouseResult.categories.performance.score → 0-1 (multiply by 100)
lighthouseResult.audits['largest-contentful-paint'].numericValue → LCP in ms
lighthouseResult.audits['cumulative-layout-shift'].numericValue → CLS score
lighthouseResult.audits['total-blocking-time'].numericValue → TBT in ms
loadingExperience.metrics → Field data (real users)
originLoadingExperience.metrics → Origin-level field data
The loadingExperience object contains real user metrics from CrUX. If the URL doesn't have enough traffic, this will be empty and you'll only get lab data.
Request Parameters
| Parameter | Required | Description |
|---|---|---|
url | Yes | URL to analyze |
key | Yes | Your API key |
strategy | No | mobile (default) or desktop |
category | No | performance, accessibility, seo, best-practices |
locale | No | Locale for the report (e.g., en_US) |
Request multiple categories by repeating the parameter:
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://example.com&key=YOUR_KEY&category=performance&category=accessibility"
Getting Started
- Get your API key — 2-minute setup in Google Cloud Console
- Choose your language — Node.js or Python
- Scale up — Bulk testing guide
- Handle limits — Rate limit strategies
Skip the Complexity
Testing URLs one at a time doesn't scale. Building queue systems, handling rate limits, and managing retries adds complexity that isn't your core product.
Unlighthouse crawls your entire site and runs Lighthouse on every page automatically. No API keys, no rate limits, no queue management.
npx unlighthouse --site https://your-site.com
For historical tracking and scheduled scans, Unlighthouse Cloud handles everything.
Try Unlighthouse Cloud