Comparing Lab and Field Data with CrUX

Lighthouse tells you how a page performs under one fixed set of conditions. The Chrome User Experience Report (CrUX) tells you how it performed for real Chrome users over the last 28 days. Teams that only look at one of them make predictable mistakes: lab-only teams tune for an emulated phone their readers do not use, and field-only teams find out about regressions a month after they shipped.

This guide pulls CrUX data for a static site's origin and key URLs, lines it up against Lighthouse CI results per template, and turns the comparison into budget changes. It is part of Performance Budgets and Lighthouse CI.

Prerequisites

• A Google Cloud API key with the Chrome UX Report API enabled (free).
• Lighthouse CI results per template, from Setting Up Lighthouse CI for a Static Site.
• Optionally, your own real-user monitoring, which fills the gaps where CrUX has no data.

Step 1: Query the CrUX API

The API takes an origin or URL and a form factor, and returns histograms and the 75th percentile for each metric.

curl -s "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$CRUX_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"origin":"https://docs.example.com","formFactor":"PHONE",
       "metrics":["largest_contentful_paint","interaction_to_next_paint","cumulative_layout_shift"]}' \
  | jq '.record.metrics | map_values(.percentiles.p75)'

{
  "largest_contentful_paint": 1840,
  "interaction_to_next_paint": 112,
  "cumulative_layout_shift": "0.03"
}

Query the origin first, then each template's most popular URL. Many URLs will return 404 NOT_FOUND because they fall below CrUX's traffic threshold; that is expected, and it is why template-level data from your own RUM becomes valuable. The CrUX History API (records:queryHistoryRecord) returns up to 40 weekly data points, which shows trends and the effect of a release more quickly than the single 28-day figure.

Step 2: Line Up Lab and Field per Template

For each template, put the Lighthouse CI median next to the field p75 from CrUX (where the URL has data) or from RUM (where it does not). A docs site with four templates, mobile:

Step 3: Explain Each Gap

A gap between lab and field is a clue, not an error. The common causes on static sites:

Field faster than lab (home, docs, blog here). Readers use faster devices than Lighthouse's emulated mid-range phone, and many arrive with a warm cache from a previous page. Documentation readers in particular browse several pages per session, so their second and later page loads skip font and CSS downloads. This is normal and healthy; it means the lab budget has headroom.

Field slower than lab (API reference here). Something real readers encounter is absent from the lab test. For this site, three things: the API reference pages are long, and real readers scroll and click the "expand all" control, which Lighthouse never does — that drove INP to 210 ms; the representative URL chosen for Lighthouse was a short reference page, while traffic concentrated on the four longest ones; and a large share of API reference readers came from regions far from the CDN's nearest edge, visible in the RUM data's country breakdown.

CLS higher in the field (blog, 0.04 lab against 0.11 field). Lighthouse measures layout shifts during load only; field CLS includes shifts during the whole visit. The blog's culprit was a lazily loaded comments embed that pushed the footer down when readers scrolled to it — a shift the lab could not see. The fix is described in Fixing CLS from Late-Loading Embeds.

Step 4: Adjust Tests and Budgets

Each explanation leads to a concrete change:

• API reference: swap the representative URL for the heaviest real page, add a Lighthouse CI user-flow step that clicks "expand all" and measures interaction, and budget TBT on that template at 100 ms. The underlying fix — rendering collapsed sections as <details> elements instead of a JavaScript accordion — brought field INP to 118 ms over the next four weeks.
• Blog: add a scripted scroll to the bottom of the page before Lighthouse finishes, so late shifts are captured, and reserve space for the embed.
• Docs and home: field comfortably beats lab, so tighten the lab LCP error thresholds by 200 ms, since the lab-to-field relationship shows readers are well protected even at the tighter limit.

The general rule: where field is worse than lab, make the lab test more realistic; where field is better, tighten the lab budget until it protects readers with a sensible margin rather than an enormous one.

Automating the Comparison

Run the comparison monthly rather than once. A scheduled workflow queries CrUX for the origin and each template's top URL, merges in RUM aggregates by template, reads the latest Lighthouse CI medians, and writes a Markdown table to an issue. Flag any template where field p75 exceeds lab median by more than 20% — that is the signal to investigate — and any where lab is more than 40% above field, which suggests the budget can tighten. The RUM side of this is described in Building a Core Web Vitals Dashboard from RUM Data.

Measured Impact

Two months after acting on the comparison:

The ramp is worth explaining to stakeholders before the fix ships. People expecting an overnight change in Search Console will otherwise conclude the work failed during the first fortnight, when the rolling window still contains mostly pre-fix visits.

Pitfalls & Rollback

• Comparing different pages. Lab tests one URL; CrUX aggregates many. Compare per template with representative URLs, or use RUM grouped by template.
• Reading a 28-day window as current. CrUX lags. Use the History API's weekly points to see recent changes.
• Ignoring form factor. Phone and desktop CrUX values can differ by 2×. Compare mobile lab to phone field, desktop to desktop.
• Loosening lab budgets to match bad field data. Make the lab test catch what the field sees instead.
• Rollback: the comparison is a report; the budget and test changes it prompts are ordinary commits that can be reverted individually.

Conclusion

Lab and field data answer different questions, and the gap between them is the most useful number in performance work. On this docs site, lining up Lighthouse medians against CrUX and RUM per template showed three templates with comfortable headroom and one where the lab test missed real reader behaviour. Tightening budgets on the first three and making the lab test realistic for the fourth took the share of URLs passing Core Web Vitals on mobile from 81% to 97% in two months.

FAQ

What is CrUX?

The Chrome User Experience Report is Google's public dataset of real-user performance from opted-in Chrome users. It reports 75th-percentile LCP, INP, CLS and other metrics per origin and for sufficiently popular URLs, over a rolling 28-day window.

Why does my Lighthouse LCP differ from CrUX LCP?

Lighthouse emulates one device and network on a cold load. CrUX aggregates real devices, networks, cache states and locations. If your readers mostly use fast desktops or return with warm caches, field LCP will be lower than lab; if they use older phones on slow networks, it will be higher.

My page has no CrUX data. What now?

CrUX only publishes URLs with enough traffic. Use origin-level data, or group URLs by template with your own real-user monitoring. For a static site, template-level RUM is usually more useful than URL-level CrUX anyway.

How long after a fix does CrUX reflect it?

The 28-day window means a fix shows up gradually and fully after four weeks. The CrUX History API's weekly data points let you see the trend start within a week or two.

Related

• Parent: Performance Budgets and Lighthouse CI — the lab side of the comparison.
• Measuring INP on Static Sites with Real-User Monitoring — collecting the field data CrUX lacks.
• Measuring CLS in the Field with web-vitals.js — where late shifts show up.
• Measuring LCP Subparts with DevTools — diagnosing a template once the gap points at it.
• Writing a Performance Budget That Fails Builds — applying the tightened limits.