# Lighthouse & PageSpeed Audit — Lab + Field Core Web Vitals (`axery/lighthouse-pagespeed-audit`) Actor

Run Google's official Lighthouse audit (PageSpeed Insights v5 API) on any URL: performance, accessibility, SEO and best-practices scores, Core Web Vitals from both lab and real-user field data, and ranked improvement opportunities.

- **URL**: https://apify.com/axery/lighthouse-pagespeed-audit.md
- **Developed by:** [Axery](https://apify.com/axery) (community)
- **Categories:** Developer tools, SEO tools, Automation
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.01 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Lighthouse / PageSpeed Insights Audit

Runs Google's official Lighthouse audit on any URL — the same audit Chrome DevTools runs locally — as a hosted, scriptable Actor. This wraps Google's own public [PageSpeed Insights v5 API](https://developers.google.com/speed/docs/insights/v5/get-started) directly; it is not a scrape.

### What you get per URL

- **Category scores** (0-100): performance, accessibility, best-practices, SEO, PWA.
- **Core Web Vitals, lab data**: this specific run's LCP, CLS, TBT, FCP, Speed Index and Time to Interactive, under fixed simulated network/CPU throttling — reproducible, synthetic.
- **Core Web Vitals, field data**: real Chrome User Experience Report percentiles for the exact URL, and a site-wide fallback when Google lacks enough traffic on that specific page. This is what real visitors experienced, not a simulation — kept separate from lab data deliberately, since a page can score badly in the lab while real users had a fine experience, or the reverse.
- **Ranked opportunities**: failing performance audits, sorted by estimated time savings in milliseconds — the fixes worth doing first, not just a wall of raw audit data.

### You need your own Google API key

This API requires a key for any real usage. Confirmed directly against the live endpoint:

| Request | Result |
|---|---|
| No key | HTTP 429 — Google's shared anonymous quota, already exhausted globally |
| Invalid key | HTTP 400 — "API key not valid" |
| Valid key | Full audit |

Getting one is free and takes a minute: in [Google Cloud Console](https://console.cloud.google.com/apis/credentials), enable the **PageSpeed Insights API** for a project, then create an API key under Credentials. No billing account is required for this API's free daily quota.

### ⚠️ Verification status

Every other Actor in this suite was tested against live, real data before shipping. **This one could not be** — no valid Google API key was available during development, and the invalid-key error path was confirmed live (see the table above) but the success-path response shape was not. The client is built directly against Google's stable, versioned, publicly documented v5 API schema, which has been unchanged for years, so this is lower-risk than reverse-engineering an undocumented site — but it is a documented risk, not a verified one.

**Please run it once with your own key and check the output against the schema before relying on it.** If anything looks off, the fix is almost certainly in `src/scraper.py`'s field mapping, not the request itself (the request format is confirmed working via the error-path test above).

### Input

| Field | Type | Notes |
|---|---|---|
| `urls` | array | URLs to audit. Each takes ~15-40 seconds — this audits pages one at a time, it does not bulk-crawl a site. |
| `apiKey` | string | Your Google PageSpeed Insights API key. Required. |
| `strategy` | enum | `mobile` or `desktop`. Google's ranking signals are mobile-first. |
| `categories` | array | Any of `performance`, `accessibility`, `best-practices`, `seo`, `pwa`. Fewer categories audit faster. |
| `locale` | string | Language for audit text, e.g. `es`, `de`. Defaults to English. |
| `proxyConfiguration` | object | Not needed — Google's own infrastructure fetches the target page, not this Actor. |

### Known limits

- **Per-URL, not per-thousand.** This is priced and used per audited page — a batch of 100 URLs is 100 real Lighthouse runs, each taking real time.
- **Field data is often absent.** `core_web_vitals_field` is null for any URL without enough real-world Chrome traffic for Google to report on — common for low-traffic or new pages. Check `core_web_vitals_field_origin` for the site-wide number in that case.
- **A failed URL is still a row.** If an audit fails (bad key, unreachable URL), that URL's row carries an `error` field instead of scores, rather than vanishing from the dataset silently.

### Local development

```bash
pip install -r requirements.txt
python test_local.py https://example.com --api-key YOUR_REAL_KEY --out sample_output.json
```

There is no `sample_output.json` committed in this folder, unlike every other Actor in this suite — see the verification status note above for why.

# Actor input Schema

## `urls` (type: `array`):

One or more URLs to run a full Lighthouse audit against. Each audit takes roughly 15-40 seconds - this is a per-page audit tool, not a bulk crawler.

## `apiKey` (type: `string`):

Your own PageSpeed Insights API key. Get one free: in Google Cloud Console, enable the "PageSpeed Insights API" for a project, then create an API key under Credentials. No billing account is required for this API's free quota. Without a key, Google's shared anonymous quota returns HTTP 429 almost immediately.

## `strategy` (type: `string`):

Which device profile Lighthouse simulates. Google's own ranking signals are mobile-first, so `mobile` is the more consequential choice for SEO.

## `categories` (type: `array`):

Which Lighthouse categories to audit: `performance`, `accessibility`, `best-practices`, `seo`, `pwa`. Requesting fewer categories makes each audit noticeably faster.

## `locale` (type: `string`):

Language for audit titles/descriptions in the response, e.g. `es`, `de`, `ja`. Leave blank for English.

## `proxyConfiguration` (type: `object`):

Not needed for the API call itself, since Google's audit runner fetches the target page from Google's own infrastructure, not through this Actor's network path.

## Actor input object example

```json
{
  "urls": [
    "https://example.com"
  ],
  "apiKey": "AIzaSy...redacted...",
  "strategy": "mobile",
  "categories": [
    "performance",
    "seo"
  ],
  "locale": "es",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `audits` (type: `string`):

One row per URL audited.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [
        "https://example.com"
    ],
    "categories": [
        "performance",
        "seo"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("axery/lighthouse-pagespeed-audit").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "urls": ["https://example.com"],
    "categories": [
        "performance",
        "seo",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("axery/lighthouse-pagespeed-audit").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [
    "https://example.com"
  ],
  "categories": [
    "performance",
    "seo"
  ]
}' |
apify call axery/lighthouse-pagespeed-audit --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,axery/lighthouse-pagespeed-audit"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/cwse1MW62mVdeXoQR/builds/qwugRSFuLGdMRqP96/openapi.json