---
title: "PageSpeed Insights API Guide"
description: "Complete guide to using the PageSpeed Insights API. Get Lighthouse performance data programmatically with 25,000 free requests per day."
canonical_url: "https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api"
last_updated: "2025-01-18"
---

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:

<table>
<thead>
  <tr>
    <th>
      Data
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Performance score
    </td>
    
    <td>
      0-100 Lighthouse score
    </td>
  </tr>
  
  <tr>
    <td>
      Core Web Vitals
    </td>
    
    <td>
      LCP, CLS, TBT lab data
    </td>
  </tr>
  
  <tr>
    <td>
      Field data
    </td>
    
    <td>
      Real Chrome user metrics (when available)
    </td>
  </tr>
  
  <tr>
    <td>
      Opportunities
    </td>
    
    <td>
      Specific optimization suggestions
    </td>
  </tr>
  
  <tr>
    <td>
      Diagnostics
    </td>
    
    <td>
      Detailed performance breakdowns
    </td>
  </tr>
</tbody>
</table>

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.

**Note:** Google is [discontinuing CrUX field data](https://developers.google.com/speed/docs/insights/release_notes) in the PSI API. For field data, consider using the [CrUX API](https://developer.chrome.com/docs/crux/guides/crux-api) directly.

## Quick Start

Test any URL with a single curl command:

```bash
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 (~240 requests per minute)
- No crawling - you must provide URLs
- Lab data only for new/low-traffic URLs

## API vs CLI vs Unlighthouse

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      PSI API
    </th>
    
    <th>
      Lighthouse CLI
    </th>
    
    <th>
      Unlighthouse
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      URLs per request
    </td>
    
    <td>
      1
    </td>
    
    <td>
      1
    </td>
    
    <td>
      Entire site
    </td>
  </tr>
  
  <tr>
    <td>
      Rate limit
    </td>
    
    <td>
      ~240/min
    </td>
    
    <td>
      None
    </td>
    
    <td>
      None
    </td>
  </tr>
  
  <tr>
    <td>
      Infrastructure
    </td>
    
    <td>
      Google servers
    </td>
    
    <td>
      Your machine
    </td>
    
    <td>
      Your machine
    </td>
  </tr>
  
  <tr>
    <td>
      Cost
    </td>
    
    <td>
      Free (25k/day)
    </td>
    
    <td>
      Free
    </td>
    
    <td>
      Free CLI
    </td>
  </tr>
  
  <tr>
    <td>
      Field data
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      No
    </td>
    
    <td>
      No
    </td>
  </tr>
  
  <tr>
    <td>
      URL discovery
    </td>
    
    <td>
      Manual
    </td>
    
    <td>
      Manual
    </td>
    
    <td>
      Automatic crawl
    </td>
  </tr>
</tbody>
</table>

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.

## How It Works

PSI runs Lighthouse on Google's servers from several data centers (including Oregon, South Carolina, Netherlands, and Taiwan). PSI automatically chooses the location based on your IP, which can affect score consistency for sites without a CDN.

- **Mobile tests** simulate a Moto G4 on a slow 4G connection with CPU throttling ([source](https://developers.google.com/speed/docs/insights/v5/about))
- **Desktop tests** run on a fast wired connection with no throttling
- **Lighthouse version:** Currently uses Lighthouse 13.0 - PWA category removed ([release notes](https://developers.google.com/speed/docs/insights/release_notes))

Scores can [vary ±5 points](https://developers.google.com/web/tools/lighthouse/variability) between runs due to network conditions and server load. For accurate monitoring, run multiple tests and use the median.

## Response Structure

Key paths in the JSON response:

```text
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

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      URL to analyze
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        key
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      Your API key
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        strategy
      </code>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      <code>
        desktop
      </code>
      
       (default) or <code>
        mobile
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        category
      </code>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      <code>
        performance
      </code>
      
      , <code>
        accessibility
      </code>
      
      , <code>
        seo
      </code>
      
      , <code>
        best-practices
      </code>
      
       (filter to reduce response size)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        locale
      </code>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Locale for the report (e.g., <code>
        en_US
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

Request multiple categories by repeating the parameter:

```bash
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://example.com&key=YOUR_KEY&category=performance&category=accessibility"
```

**Tip:** Full responses can be large (up to several MBs) as they include the complete Lighthouse JSON. [Filtering by category](https://developers.google.com/speed/docs/insights/v5/reference/pagespeedapi/runpagespeed#parameters) reduces response size significantly.

For origin-level CrUX data instead of URL-specific, use the [`origin:` prefix](https://developers.google.com/speed/docs/insights/v5/get-started):

```bash
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=origin:https://example.com&key=YOUR_KEY"
```

## Getting Started

1. **Get your API key**: 2-minute setup in Google Cloud Console
2. **Choose your language**: [Node.js](/learn-lighthouse/pagespeed-insights-api/node-example) or [Python](/learn-lighthouse/pagespeed-insights-api/python-example)
3. **Scale up**: [Bulk testing guide](/learn-lighthouse/pagespeed-insights-api/bulk-testing)
4. **Handle limits**: [Rate limit strategies](/learn-lighthouse/pagespeed-insights-api/rate-limits)

## 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.

```bash
npx unlighthouse --site https://your-site.com
```

For historical tracking and scheduled scans, [Unlighthouse Cloud](/cloud) handles everything.

<u-button icon="i-heroicons-rocket-launch" label="Try Unlighthouse Cloud" size="lg" to="/">



</u-button>