Core Web Vitals report with Lighthouse and page speed evidence.

Run this report from the CLI, an MCP client, or application code. Every surface uses the same report definition and returns the same evidence. JSON is the source of truth; Markdown makes it readable without hiding dates, limits, warnings, or skipped work.

What this report helps you decide

What does lab diagnosis and available field data say about this URL’s performance?

• A page needs LCP, INP, CLS, TBT, or loading diagnostics.
• You can reproduce the tested URL and device strategy.

Command facts

Report id

performance-audit

Execution

Local process

Outputs

JSON and Markdown

Example parameters

url, strategy, refresh

Agent discovery

seo reports describe performance-audit --json

Interactive prompts

Human CLI commands only

When this report is not the right tool

These cases need a different report, more evidence, or a human decision. Do not force this report to answer a question its data cannot support.

• You need technical SEO evidence beyond loading performance for this URL. Recommended report: Audit one page. Audit the page to add redirects, canonicals, directives, metadata, headings, links, schema, and content evidence. Lighthouse and CrUX do not answer those questions.
• You need to conclude that one Lighthouse run represents every page using the same template. No automated report can generalise one lab run to a whole template. Select representative URLs across device, traffic, content, and template states, run the audit for each, and compare available URL-level or origin-level CrUX coverage separately.

Data sources and inputs

• Local Lighthouse navigation. Provides lab performance metrics, diagnostics, and opportunities for the selected device strategy.
• Optional CrUX field data. Provides device-specific p75 Core Web Vitals when the URL or origin has enough eligible traffic.

What this report checks

• Runs Lighthouse locally and records the tested URL, strategy, environment, metrics, and diagnostic opportunities.
• Reports URL or origin CrUX coverage separately and never substitutes lab TBT for field INP.

How it works

• Keeps lab, field, unavailable, and fetch-fallback states separate and reports the device, collection scope, and thresholds used.

The JSON result keeps dates, thresholds, limits, skipped work, and source completeness beside the finding. Missing, partial, capped, filtered, and complete data remain different states.

Run the report from the CLI

Run a local Lighthouse test and add available CrUX evidence. Agents and CI should inspect the live schema before their first run.

seo perf audit --url https://example.com/page

seo reports describe performance-audit --json

seo reports run performance-audit --params '{"url":"https://example.com/","strategy":"mobile","refresh":true}' --json

Project profiles can fill supported property and analytics inputs for the human-facing commands. The catalog form shown here is explicit by design, so agents and CI jobs do not prompt or guess.

How an MCP agent should use it

Call seo_describe_report first so the agent sees when this report is useful and gets the current input schema. Then callseo_run_report with the validated parameters. Read the status, warnings, source limits, and skipped sections before acting on a finding.

{
  "id": "performance-audit"
}

{
  "id": "performance-audit",
  "params": {
    "url": "https://example.com/",
    "strategy": "mobile",
    "refresh": true
  }
}

Use a follow-up report returned by the result instead of guessing the next tool. The local MCP server and CLI use the same report definition and evidence. Their outer transport envelopes differ.

Use the report in a TypeScript app

Install seo as a project dependency, then call the same report catalog used by the CLI and MCP. executeReportrejects an unknown report id or invalid parameters. Provider and runtime failures come back as structured results withisError set.

npm install seo

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'performance-audit',
  {
  "url": "https://example.com/",
  "strategy": "mobile",
  "refresh": true
},
)

console.log(result)

The TypeScript library guide also covers direct core functions, schema discovery, and the difference betweenexecuteReport and runReport.

What comes back and how to read it

• A lab performance summary with Lighthouse metrics, diagnostics, and the strongest reproducible bottlenecks.
• Available CrUX LCP, INP, and CLS evidence with device, scope, thresholds, and unavailable states shown explicitly.
• Prefer applicable field evidence for real-user experience. Use lab insights to reproduce and diagnose, then verify changes in both contexts.

Start with dataStatus, source details, warnings, and caveats. Then inspect the observed evidence before derived findings or suggested actions.

What this report cannot tell you

• CrUX may have no coverage. A Lighthouse run varies with the machine, network, page state, and loaded third parties.

What to do next

1. Fix the returned bottleneck with the strongest evidence and rerun under the same conditions.
2. Check representative templates rather than assuming one page describes the whole site.

Related reports

• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
• Crawl a site for technical SEO issues. Map a limited part of a site, run the maintained technical checks, and save a reusable evidence baseline.
• Measure an SEO change. Compare equal, finalised search windows around a recorded change and see what moved without claiming the change caused it.

Sources behind the guidance

These primary sources define the provider data or search controls used in the interpretation above.

• Core Web Vitals metrics and thresholds

Browse all reports in AI search evidence.