# Lighthouse Website Auditor (`constant_quadruped/lighthouse-auditor`) Actor

Run Google Lighthouse audits on any URL. Get performance, accessibility, SEO, and best practices scores with Core Web Vitals (LCP, FCP, TBT, CLS). Supports mobile and desktop emulation, configurable throttling, and optional HTML reports. Fast, accurate, pay-per-use pricing.

- **URL**: https://apify.com/constant_quadruped/lighthouse-auditor.md
- **Developed by:** [CQ](https://apify.com/constant_quadruped) (community)
- **Categories:** SEO tools, Developer tools
- **Features:** Limited permissions
- **Stats:** 317 total users, 71 monthly users, 99.8% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Lighthouse Auditor

Run Google Lighthouse audits on any URL and get performance, accessibility, SEO, and best practices scores with Core Web Vitals metrics.

### What does Lighthouse Auditor do?

This Actor runs [Google Lighthouse](https://developers.google.com/web/tools/lighthouse) audits programmatically via Apify. It launches a real Chrome browser, navigates to your target URL, and returns detailed scores and metrics — the same data you'd get from Chrome DevTools, but automated and at scale.

**Key capabilities:**

- **Performance scores** (0-100) for each audit category
- **Core Web Vitals** — LCP, FCP, TBT, CLS, TTI, SI with good/needs-improvement/poor ratings
- **Failing audits** — top 10 worst-scoring audits so you know what to fix
- **Optimization opportunities** — potential time and byte savings, sorted by impact
- **Mobile and desktop** device emulation
- **Configurable throttling** — simulated, DevTools, or none
- **Optional HTML reports** saved to key-value store

### Why use this Actor?

| Use Case | How It Helps |
|----------|--------------|
| **SEO Monitoring** | Track SEO scores across all your sites on a schedule |
| **Performance Budgets** | Alert when scores drop below your thresholds |
| **Competitor Analysis** | Compare your Core Web Vitals vs competitors |
| **CI/CD Integration** | Block deployments if Lighthouse scores fail |
| **Client Reporting** | Generate automated audit reports for clients |
| **Bulk Auditing** | Audit hundreds of URLs without manual work |

### How much does it cost to run?

This Actor uses approximately **0.1–0.3 compute units** per audit, depending on:

- Page complexity (more resources = longer audit)
- Number of categories selected
- Whether HTML report is saved

At current Apify pricing, expect roughly **$0.01–0.03 per audit**.

### Input

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `url` | String | Yes | — | The URL to audit (`https://` is added automatically if missing) |
| `device` | String | No | `mobile` | Device to emulate: `mobile` or `desktop` |
| `categories` | Array | No | All | Which categories to audit. Options: `performance`, `accessibility`, `best-practices`, `seo` |
| `saveHtmlReport` | Boolean | No | `false` | Save the full HTML Lighthouse report to key-value store |
| `throttling` | String | No | `simulated` | Network throttling preset: `simulated` (fast), `devtools` (accurate), or `none` (full speed) |

#### Input example

```json
{
    "url": "https://example.com",
    "device": "mobile",
    "categories": ["performance", "seo"],
    "saveHtmlReport": true,
    "throttling": "simulated"
}
```

### Output

Results are saved to the default dataset with scores (0-100) and Core Web Vitals metrics.

#### Output fields

| Field | Type | Description |
|-------|------|-------------|
| `url` | String | The final URL after redirects |
| `requestedUrl` | String | The original URL requested |
| `device` | String | Device type used for the audit |
| `timestamp` | String | ISO timestamp of the audit |
| `performance` | Number | Performance score (0-100) |
| `accessibility` | Number | Accessibility score (0-100) |
| `bestPractices` | Number | Best Practices score (0-100) |
| `seo` | Number | SEO score (0-100) |
| `coreWebVitals` | Object | Core Web Vitals metrics with ratings (see below) |
| `failingAudits` | Array | Top 10 worst-scoring audits (score < 50), sorted worst first |
| `opportunities` | Array | Top 10 optimization opportunities, sorted by potential time savings |
| `lighthouseVersion` | String | Version of Lighthouse used |
| `throttling` | String | Throttling preset used |
| `htmlReportKey` | String | Key-value store key for HTML report (when `saveHtmlReport` is true) |
| `htmlReportUrl` | String | Direct URL to the HTML report (when `saveHtmlReport` is true) |

#### Output example

```json
{
    "url": "https://example.com/",
    "requestedUrl": "https://example.com",
    "device": "mobile",
    "timestamp": "2025-01-15T10:30:00.000Z",
    "performance": 85,
    "accessibility": 92,
    "bestPractices": 100,
    "seo": 90,
    "coreWebVitals": {
        "FCP": 1200,
        "FCP_rating": "good",
        "LCP": 2500,
        "LCP_rating": "good",
        "TBT": 150,
        "TBT_rating": "good",
        "CLS": 0.1,
        "CLS_rating": "good",
        "SI": 3200,
        "SI_rating": "good",
        "TTI": 3800,
        "TTI_rating": "good"
    },
    "failingAudits": [
        {
            "id": "render-blocking-resources",
            "title": "Eliminate render-blocking resources",
            "score": 0,
            "displayValue": "Potential savings of 1,230 ms",
            "description": "Resources are blocking the first paint of your page."
        }
    ],
    "opportunities": [
        {
            "id": "unused-javascript",
            "title": "Reduce unused JavaScript",
            "savingsMs": 1200,
            "savingsBytes": 245760,
            "displayValue": "Potential savings of 240 KiB"
        }
    ],
    "lighthouseVersion": "12.x.x",
    "throttling": "simulated"
}
```

### Core Web Vitals reference

Core Web Vitals are Google's key metrics for page experience. Here's how to interpret the values:

| Metric | Full Name | Good | Needs Work | Poor | Unit |
|--------|-----------|------|------------|------|------|
| **LCP** | Largest Contentful Paint | ≤2500 | ≤4000 | >4000 | ms |
| **FCP** | First Contentful Paint | ≤1800 | ≤3000 | >3000 | ms |
| **TBT** | Total Blocking Time | ≤200 | ≤600 | >600 | ms |
| **CLS** | Cumulative Layout Shift | ≤0.1 | ≤0.25 | >0.25 | score |
| **SI** | Speed Index | ≤3400 | ≤5800 | >5800 | ms |
| **TTI** | Time to Interactive | ≤3800 | ≤7300 | >7300 | ms |

### Throttling options explained

| Option | Speed | Accuracy | Use Case |
|--------|-------|----------|----------|
| `simulated` | Fast | Good | Quick audits, bulk testing |
| `devtools` | Slow | Excellent | Accurate performance data |
| `none` | Fastest | Variable | When you only need scores, not timing |

**Recommendation:** Use `simulated` for most cases. Use `devtools` when you need accurate Core Web Vitals for performance debugging.

### Integrations

#### Schedule regular audits

Use Apify Scheduler to run audits daily, weekly, or hourly. Track scores over time by exporting to a database.

#### Send alerts

Connect to Zapier or Make to send Slack/email alerts when scores drop below thresholds.

#### CI/CD pipelines

Call this Actor from GitHub Actions, GitLab CI, or Jenkins to gate deployments on Lighthouse scores.

#### Example: GitHub Actions

```yaml
- name: Run Lighthouse Audit
  run: |
    curl -X POST "https://api.apify.com/v2/acts/YOUR_ACTOR/runs?token=${{ secrets.APIFY_TOKEN }}" \
      -d '{"url": "${{ github.event.deployment.url }}", "device": "mobile"}'
```

### Limitations

- One URL per run (for bulk audits, run multiple times or modify the Actor)
- Some sites may block headless Chrome — results may vary
- Maximum runtime: 5 minutes per audit

### Changelog

- **v2.1** — Added failing audits, optimization opportunities, CWV ratings, fixed HTML report as single dataset row
- **v2.0** — Updated for Lighthouse 12, removed PWA category, improved stability
- **v1.0** — Initial release with full Lighthouse 11 support

### Support

Questions or issues? Contact the developer or open an issue on the Actor's page.

***

**Built by** [Jaclyn](https://spiderontheweb.com)

# Actor input Schema

## `url` (type: `string`):

The URL to audit (https:// is added automatically if missing)

## `device` (type: `string`):

Emulate mobile or desktop device

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

Which Lighthouse categories to run (leave empty for all). Note: PWA category was removed in Lighthouse 12.

## `saveHtmlReport` (type: `boolean`):

Store the full HTML report in key-value store

## `throttling` (type: `string`):

Network throttling preset

## Actor input object example

```json
{
  "url": "https://example.com",
  "device": "mobile",
  "categories": [
    "performance",
    "accessibility",
    "best-practices",
    "seo"
  ],
  "saveHtmlReport": false,
  "throttling": "simulated"
}
```

# Actor output Schema

## `auditResults` (type: `string`):

Lighthouse scores and Core Web Vitals in a table view

## `rawOutput` (type: `string`):

Complete audit results as raw JSON

# 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 = {
    "url": "https://example.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("constant_quadruped/lighthouse-auditor").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 = { "url": "https://example.com" }

# Run the Actor and wait for it to finish
run = client.actor("constant_quadruped/lighthouse-auditor").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 '{
  "url": "https://example.com"
}' |
apify call constant_quadruped/lighthouse-auditor --silent --output-dataset

```

## MCP server setup

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

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/1ct0N2OsH98d0Vr4b/builds/rkTdK761QMJea80TH/openapi.json