Open data & tools

Chrome UX Report (CrUX) for publishers: field Core Web Vitals for any popular site

Last updated Published By the editorial team6 min5 sources

Key takeaways

  • The Chrome UX Report (CrUX) is Google's public dataset of real-user experience metrics from opted-in Chrome users, published under a Creative Commons Attribution 4.0 licence.
  • A page or origin appears in CrUX only if it is publicly discoverable and sufficiently popular; Google does not disclose the popularity threshold.
  • The CrUX API returns a 28-day rolling aggregate updated daily around 04:00 UTC and allows 150 queries per minute per Google Cloud project at no charge.
  • The BigQuery dataset chrome-ux-report is released monthly, on the second Tuesday of the following month, with ready-made summary tables such as materialized.device_summary.
  • Since September 2026 CrUX documents experimental ad metrics (ad count, ad density, ad CPU and ad kilobytes), reported only for sites whose ads.txt lists at least one authorized seller.
A Grafana monitoring dashboard with time-series graphs
Image: Grafana dashboard (2016),Linux Screenshots from USA,CC BY 2.0,via Wikimedia Commons.

The Chrome UX Report (CrUX) is Google’s free public dataset of how real Chrome users experience popular websites: Largest Contentful Paint, Interaction to Next Paint, Cumulative Layout Shift and more, at the 75th percentile. You can query it for your own origin or any competitor’s through a REST API or BigQuery. For ad-funded sites it is the cheapest way to see whether ads hurt real users.

Who is in CrUX, and who is not?

The CrUX methodology sets two conditions for a page or origin:

  • Publicly discoverable. The same indexability rules as search engines: a non-200 status, an X-Robots-Tag: noindex header or a robots noindex meta tag disqualifies a page.
  • Sufficiently popular. Google does not publish the threshold.

Data comes only from Chrome users who have usage statistics reporting enabled, browser history sync turned on and no Sync passphrase, on desktop Chrome (Windows, macOS, ChromeOS, Linux) and Android Chrome (including Custom Tabs and WebAPKs). Chrome on iOS, Android WebView apps and other Chromium browsers such as Microsoft Edge do not contribute.

That matters for publishers: if much of your audience reads you inside a social app’s in-app browser (often a WebView) or on iPhone, CrUX describes only part of it. Your own real-user measurement fills the gap; see measuring Core Web Vitals with web-vitals.

The methodology states that CrUX datasets are licensed under Creative Commons Attribution 4.0 International, so you can publish charts built on them with attribution.

How do I query the CrUX API?

The CrUX API has one endpoint, records:queryRecord, and needs a Google Cloud API key enabled for the “Chrome UX Report API”.

  1. Create a key (the CrUX docs point to goo.gle/crux-api-key) and restrict it to the Chrome UX Report API.
  2. Send a POST with either origin or url, an optional formFactor (DESKTOP, PHONE or TABLET) and an optional metrics list.
  3. Read record.metrics.<metric>.percentiles.p75 and the histogram densities.
curl -s -X POST \
  "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$CRUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "https://www.example.com",
    "formFactor": "PHONE",
    "metrics": ["largest_contentful_paint",
                "interaction_to_next_paint",
                "cumulative_layout_shift"]
  }'

The response has this shape (values here are illustrative, not from a real call):

{
  "record": {
    "key": { "formFactor": "PHONE", "origin": "https://www.example.com" },
    "metrics": {
      "largest_contentful_paint": { "percentiles": { "p75": 2810 } },
      "cumulative_layout_shift": { "percentiles": { "p75": "0.12" } }
    },
    "collectionPeriod": {
      "firstDate": { "year": 2026, "month": 10, "day": 18 },
      "lastDate": { "year": 2026, "month": 11, "day": 14 }
    }
  }
}

Operational facts from the documentation:

Item Value
Aggregation window 28-day rolling
Refresh daily, around 04:00 UTC, best effort, no SLA
Lag about two days behind the current date
Quota 150 queries per minute per Google Cloud project, free, not purchasable
No data HTTP 404, message “chrome ux report data not found”

The CrUX History API (records:queryHistoryRecord) returns weekly collection periods: 25 by default, up to 40 with collectionPeriodCount. It is updated each Monday around 04:00 UTC and uses the same key. This is the quickest way to see whether a layout change (for example, adding an in-article unit) moved CLS over the following weeks.

What are the new CrUX ad metrics?

The API now lists four experimental metrics: experimental_ad_count, experimental_ad_density, experimental_ad_cpu (milliseconds) and experimental_ad_kilobytes (KB), each reported at p75 only, and only for pages included in ad metrics. They are marked “n/a” for BigQuery.

The Chrome ad metrics methodology, published September 15, 2026, explains the rules:

  • Only sites that list at least one authorized seller in ads.txt are included. Origins with no ads.txt, or only a placeholder record, are excluded.
  • An ad counts if at least one of its pixels is in the viewport; overlapping ads each count.
  • The viewport is sampled once per second, and collection pauses while the tab is in the background.
  • Ads hidden with display: none are excluded from count and density, but their CPU and network cost still counts.
  • Chrome DevTools has an Ads panel that shows these metrics locally for any page you inspect.

For AdSense publishers this is the first public, field-based view of ad load. Two practical uses: compare your ad density with sites in your niche before adding units, and check that ad CPU time did not spike after enabling a new format. A correct ads.txt is the entry ticket; see ads.txt syntax.

curl -s -X POST \
  "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$CRUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin": "https://www.example.com", "formFactor": "PHONE",
       "metrics": ["experimental_ad_count", "experimental_ad_density"]}'

If the fields are missing from the response, CrUX has no ad data for that origin.

How do I use CrUX in BigQuery?

The CrUX BigQuery documentation describes the project chrome-ux-report, released on the second Tuesday of the following month:

Dataset / table Contents
all.YYYYMM raw monthly histograms for every origin
country_CC.YYYYMM the same, per country
materialized.metrics_summary one row per origin and month with p75 values and good/needs improvement/poor fractions
materialized.device_summary the same, split by device
materialized.country_summary split by country and device

The summary tables are small, which keeps you inside the BigQuery free tier. This query is adapted from the official samples in the GoogleChrome/CrUX repository (sql/mastering-crux/03-device-cwv.sql):

-- Monthly Core Web Vitals by device for one origin
SELECT
  yyyymm,
  device,
  p75_lcp,
  fast_lcp / (fast_lcp + avg_lcp + slow_lcp) AS pct_good_lcp,
  p75_inp,
  fast_inp / (fast_inp + avg_inp + slow_inp) AS pct_good_inp,
  p75_cls,
  small_cls / (small_cls + medium_cls + large_cls) AS pct_good_cls
FROM `chrome-ux-report.materialized.device_summary`
WHERE date >= '2025-11-01'
  AND origin = 'https://www.example.com'
  AND device IN ('desktop', 'phone')
ORDER BY yyyymm DESC, device;

The repository comment notes that metrics_summary is partitioned by date in YYYY-MM-01 form, so the date filter is what keeps the scan small.

Compare yourself with competitors

Replace the single origin with a list: origin IN ('https://a.example', 'https://b.example'). Put sites with similar audiences side by side (same country mix, same mobile share). Comparing a recipe blog with a news site tells you little, because LCP depends heavily on page type.

How should a publisher read the numbers?

  • Use the 75th percentile. The thresholds used in the web-vitals library are 2,500 ms / 4,000 ms for LCP, 200 ms / 500 ms for INP and 0.1 / 0.25 for CLS (good / poor boundaries).
  • Split by device. Ad layouts differ between phones and desktops, and an origin-wide number can hide a poor phone CLS.
  • Watch the window. A fix you shipped yesterday will take up to 28 days to show fully in the API, and a month or more in BigQuery.
  • CrUX includes iframes, your scripts do not. The web-vitals documentation notes that its APIs cannot see inside iframes, while CrUX can. Ads render in iframes, so CrUX may report layout shifts your own monitoring misses.

A simple monthly routine works for most ad-supported sites:

  1. Query the API for your origin with formFactor set to PHONE, then DESKTOP, and note the p75 for LCP, INP and CLS.
  2. Pull the History API series for the same origin and check whether the last few collection periods moved after an ad layout change.
  3. Query your three most important templates as individual URLs, if they have enough traffic to be included.
  4. Write the values and the date in a simple log, next to the changes you made. Without that log, a slow drift is impossible to explain later.

For fixes, see ads and Core Web Vitals and reserving space to prevent CLS.

Common mistakes

  • Querying www.example.com when the canonical origin is example.com, then concluding the site has no data.
  • Putting the API key in client-side code on a public page. Call the API from a server or a script.
  • Treating a missing ad metric as “no ads”. It means no data, often because ads.txt has no authorized seller.
  • Comparing a lab Lighthouse score with CrUX p75 values. They measure different things; see Lighthouse CI on ad-heavy pages for the lab side.

Open-source tools mentioned

Frequently asked questions

Why does the CrUX API say "chrome ux report data not found" for my site?

The API returns a 404 with that message when it has no data for the origin or URL. Common causes are a mismatch in the origin you typed (http instead of https, an extra or missing www), a page that is not publicly discoverable (noindex or non-200 status), or too few eligible Chrome users. Try the origin instead of the URL, and the exact canonical hostname.

Is CrUX the same data as Search Console's Core Web Vitals report?

Both come from Chrome field data, and the web-vitals library documentation says it measures metrics the same way they are reported to CrUX, PageSpeed Insights and Search Console. The tools aggregate differently (by page, URL group or origin, and over different windows), so numbers rarely match exactly. Use CrUX when you need raw p75 values or competitor data.

Can I see a competitor's ad density in CrUX?

Only if CrUX reports ad metrics for that site. The Chrome ad metrics methodology says only sites listing at least one authorized seller in ads.txt are included, and the API documents the four experimental ad metrics as p75 values for pages included in ad metrics. They are not available in the BigQuery tables. A missing field means no data, not zero ads.

Do I need to pay to use CrUX?

The API is free within its quota of 150 queries per minute per Google Cloud project, and that quota cannot be increased by paying. BigQuery queries are billed by bytes processed after the monthly free tier, so use the small materialized summary tables and filter on date and origin to stay within it.

Sources

  1. CrUX methodology · Chrome for Developers
  2. CrUX API · Chrome for Developers
  3. CrUX History API · Chrome for Developers
  4. CrUX on BigQuery · Chrome for Developers
  5. Chrome ad metrics methodology · Chrome for Developers