The CrUX API, history, and BigQuery
Ask CrUX for field data from your own code, follow a fix week by week with the History API and CrUX Vis, query BigQuery's monthly tables, and compare sites.
- 01Ask CrUX from your own codeSend a CrUX API request for an origin or a page, read the record it sends back, and handle the 404 it sends when it has no data.
- 02Follow a fix week by weekRead the History API's overlapping 28-day periods, and CrUX Vis's charts of them, and say why a fix takes weeks to show.
- 03Query BigQuery and compare sites fairlyQuery CrUX's monthly tables with SQL, and compare your site with a competitor's by form factor, not by one overall number.
Asking CrUX from your own code
Ravi has fixed the jump on the Mint tea page. In the last lesson, the reviews box arrived late and pushed the photo down. Now the page keeps room for the box from the start. The fix went live on Sunday, February 1.
Then Ravi waited for CrUX, Chrome's report of real visits, to notice. Here is what it said about the page's CLS on phones, week after week:
// The Mint tea page's CLS p75 on phones, one 28-day window per weekconst windows = ["Jan 4 to Jan 31", "Jan 11 to Feb 7", "Jan 18 to Feb 14", "Jan 25 to Feb 21", "Feb 1 to Feb 28"];const p75s = ["0.17", "0.17", "0.17", "0.00", "0.00"]; windows.forEach((days, i) => console.log(`${days}: ${p75s[i]}`)); - Line 1 is a comment. CLS, Cumulative Layout Shift, measures how much a page jumps. It's good at 0.1 or less.
- Line 2 holds five windows of 28 days. Each one ends a week after the one before.
- Line 3 holds the p75 CrUX gave for each window: three in four page loads had that CLS or less.
- Line 5 prints one line per window. The first is
Jan 4 to Jan 31: 0.17, and the last isFeb 1 to Feb 28: 0.00.
The fix went live on February 1. Yet the next two answers still said 0.17, as if nothing had changed. Did the fix fail? And how did Ravi get these numbers from his own code, without opening PageSpeed Insights each week? This lesson answers both questions.
CrUX has four doors you can knock on from your own code or browser:
- The CrUX API: a web address your code calls. It answers with the latest 28 days, for a whole site or one page.
- The History API: the same question, but one 28-day window per week, for up to 40 weeks.
- CrUX Vis: a website that draws the History API's answers as charts. No code needed.
- BigQuery: Google's database for huge tables. CrUX puts one table there each month, with every site in it. You ask it questions in SQL.
In The Chrome User Experience Report, CrUX was a weather board: the last 28 days together. Now picture the weather service's four counters. At the first, you phone and hear today's figure for one town. At the second, you get the board's figure for every Monday, months back. The third has the same log drawn as charts on a wall. The fourth is a library of printed monthly reports, one for every town.
- In real life: Phoning for today's 28-day figure
- In CrUX: The CrUX API: the latest 28 days
- In real life: The log of the board, read every Monday
- In CrUX: The History API: one 28-day window per week
- In real life: The wall of charts drawn from the log
- In CrUX: CrUX Vis
- In real life: The library of monthly reports for every town
- In CrUX: BigQuery: one table per month, every site
Here are Ravi's eight weeks, and the windows each door reads from them:
Every bar under the weeks is the same thing: 28 days of visits. The CrUX API reads the latest window. The History API reads one window per week, so its windows overlap. BigQuery reads one window per month. Look at the second History API bar: only one of its four weeks comes after the fix.
How the course recorded it
- Weeks 1 to 4 are the capstone's 480 visits to Leaf and Kettle, from Capstone: audit a real site. Each page sent home its own numbers through the RUM pipeline from Project: build a RUM dashboard. The last lesson read the same visits.
- Weeks 5 to 8 are 480 more visits, made the same way in Chrome 157, with Ravi's fix live. Each visitor's phone or computer, and network, were drawn as in Reading performance data.
- Teapot Lane, a second shop for the end of the lesson, is the same four pages under another name, with two of the capstone's fixes in. It had 240 visits in weeks 5 to 8, 7 in 10 of them from computers.
- The examples date the weeks from Sunday, January 4 to Saturday, February 28.
- Each answer, and each BigQuery table, lays those visits out the way CrUX's docs describe its data. Shares are rounded to 4 decimal places, as CrUX rounds them.
Every CrUX number covers a 28-day window of real Chrome visits. The CrUX API gives the latest window, the History API one window a week, CrUX Vis draws them, and BigQuery keeps one window a month for every site. Pick the door by your question: today, the trend, or many sites at once.
The CrUX API: one question, one record
PageSpeed Insights shows CrUX's numbers on a web page. The CrUX API sends the same numbers to your own code, as JSON. So a script can check every page each morning, keep the answers, and warn you when one gets worse.
Getting a key
The API needs an API key: a long code that says which Google Cloud project is asking. You get one in two steps:
- Create a project in the Google Cloud console. A project holds your settings and your keys.
- On the project's Credentials page, create an API key for the Chrome UX Report API. The API's docs have a Get a Key button that does it for you.
Then add the key to each request's address as key=. The same key works for the History API. Each project can ask 150 questions a minute, for free.
Asking a question
A question is a POST request to one address, with a small JSON body. The body has three parts:
originorurl: the whole site, or one page. You give one of them, never both.formFactor:PHONE,DESKTOPorTABLET. Leave it out to get all three added together.metrics: the names of the metrics you want. Leave it out to get every metric CrUX has.
// Ask CrUX for the whole site's LCP on phones. API_KEY is your own key.const endpoint = "https://chromeuxreport.googleapis.com/v1/records:queryRecord";const response = await fetch(`${endpoint}?key=${API_KEY}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ origin: "https://leafandkettle.example", formFactor: "PHONE", metrics: ["largest_contentful_paint"], }),});const answer = await response.json(); - Line 2 is the API's address. Line 3 adds the key, and sends the request with
fetch. - Line 4 makes it a POST, and line 5 says the body is JSON.
- Lines 6 to 10 are the body: the site, phones only, and one metric, LCP.
- Line 12 reads the answer as JSON.
Reading the record
Ravi ran this on Monday, February 2. CrUX answers with a record: an object that holds what you asked about, the metrics, and the dates they cover. Here it is, with the course's numbers:
// CrUX's answer on Monday, February 2const answer = { record: { key: { formFactor: "PHONE", origin: "https://leafandkettle.example" }, metrics: { largest_contentful_paint: { histogram: [ { start: 0, end: 2500, density: 0.5387 }, { start: 2500, end: 4000, density: 0.2411 }, { start: 4000, density: 0.2202 }, ], percentiles: { p75: 3888 }, }, }, collectionPeriod: { firstDate: { year: 2026, month: 1, day: 4 }, lastDate: { year: 2026, month: 1, day: 31 }, }, },}; const lcp = answer.record.metrics.largest_contentful_paint;console.log(`p75: ${lcp.percentiles.p75} ms`);console.log(`Good: ${(lcp.histogram[0].density * 100).toFixed(1)}% of page loads`); - Line 4 is the
key. It repeats what you asked: phones, and the whole site. - Lines 8 to 10 are the
histogram: three bins, for good, needs improvement and poor. Each bin'sdensityis its share of the page loads, rounded to 4 decimal places. The last bin has no end. - Line 12 is the p75. The docs call it "synthetically derived": worked out from all the page loads, not from the three bins.
- Lines 15 to 18 are the
collectionPeriod: the 28 days the numbers cover, January 4 to 31. The API runs about two days behind, so on Monday it reaches the Saturday before. - Lines 23 and 24 print
p75: 3888 msandGood: 53.9% of page loads.
You've seen these numbers before. In the last lesson, PageSpeed Insights gave the site's LCP on phones as 3,888 ms. It reads the same CrUX data. Why it matters: in your own code, you can now store an answer every day and draw your own charts.
One metric looks different. The API sends CLS as text with two decimal places, like "0.17", and its bins start at "0.00", "0.10" and "0.25". Turn it into a number with Number() before you compare it.
A page, and the 404
To ask about one page, send url instead of origin. Ask about something CrUX has no data for, and you get an error instead of a record. None of Leaf and Kettle's visitors used a tablet:
// The API's answer when it has no data: Leaf and Kettle on tabletsconst response = { status: 404, body: { error: { code: 404, message: "chrome ux report data not found", status: "NOT_FOUND" } } }; function recordOf(response) { if (response.status === 404 && response.body.error?.status === "NOT_FOUND") return null; return response.body.record;}console.log(recordOf(response) ?? "No CrUX data for this question"); - Line 2 is the answer: status
404, and anerrorwhose status isNOT_FOUND. - Lines 4 to 7 read an answer. Line 5 turns a 404 into "no record".
- Line 8 prints
No CrUX data for this question.
Chrome's own DevTools reads a 404 the same way. Its CrUX code calls it "how CrUX tells us that there is not data available", and treats it as no data, not as a failure. The API guide lists the usual causes:
- The address isn't the one people really reach:
httpinstead ofhttps, or a missingwww. - The page isn't public, or it has too few page loads.
- The question is too narrow: a less popular URL, or the less popular tablet form factor.
Try it yourself. Pick a page, a device and a day, and read the answer:
{
"origin": "https://leafandkettle.example",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"interaction_to_next_paint",
"cumulative_layout_shift"
]
}{
"record": {
"key": { "formFactor": "PHONE", "origin": "https://leafandkettle.example" },
"metrics": {
"cumulative_layout_shift": {
"histogram": [
{ "start": "0.00", "end": "0.10", "density": 0.7351 },
{ "start": "0.10", "end": "0.25", "density": 0.2649 },
{ "start": "0.25", "density": 0 }
],
"percentiles": { "p75": "0.17" }
},
"interaction_to_next_paint": {
"histogram": [
{ "start": 0, "end": 200, "density": 0.7381 },
{ "start": 200, "end": 500, "density": 0.2619 },
{ "start": 500, "density": 0 }
],
"percentiles": { "p75": 232 }
},
"largest_contentful_paint": {
"histogram": [
{ "start": 0, "end": 2500, "density": 0.5387 },
{ "start": 2500, "end": 4000, "density": 0.2411 },
{ "start": 4000, "density": 0.2202 }
],
"percentiles": { "p75": 3888 }
}
},
"collectionPeriod": {
"firstDate": { "year": 2026, "month": 1, "day": 4 },
"lastDate": { "year": 2026, "month": 1, "day": 31 }
}
}
}Read the key first: it echoes what you asked. Then each metric's histogram and p75, and the collection period: the 28 days the numbers cover.
LCP subparts, round trips, and navigation types
In the last lesson, the home page's LCP was poor on phones: a p75 of 4,588 ms. CrUX can't name the slow element. But it has metrics that say which part of the wait is slow, and who your visitors are.
Image or text?
largest_contentful_paint_resource_type splits LCPs into images and text, as fractions: shares that add up to about 1. On phones, the home page answered image: 1 and text: 0. Every phone visit's LCP was the slider photo. Why it matters: the next four metrics count image LCPs only.
The four subparts
Remember the pizza with four waits from The four parts of LCP? CrUX reports each wait as a metric of its own:
largest_contentful_paint_image_time_to_first_byte: until the page's first byte arrives...._resource_load_delay: until the browser asks for the photo...._resource_load_duration: until the photo's last byte arrives...._element_render_delay: until the photo is on screen.
Each one is a p75 only, with no histogram. CrUX counts them on full page loads with an image LCP. Here are the four waits on one load of the home page:
The text appears quickly. The photo's spot stays grey for seconds. Now the field numbers, for every phone visit from January 4 to 31:
// The home page on phones: the LCP p75, and each image subpart's p75const lcpP75 = 4588;const parts = { time_to_first_byte: 248, resource_load_delay: 2863, resource_load_duration: 1513, element_render_delay: 21,}; const [biggest] = Object.entries(parts).sort((a, b) => b[1] - a[1]);const sum = Object.values(parts).reduce((total, ms) => total + ms, 0);console.log(`Biggest part: ${biggest[0]}, ${biggest[1]} ms`);console.log(`The four p75s add up to ${sum} ms, not ${lcpP75}`); - Line 2 is the LCP p75. Lines 4 to 7 are the four subparts' p75s, each named by the end of its metric's name.
- Line 10 sorts the parts, longest first, and keeps the first.
- Line 11 adds the four together.
- Lines 12 and 13 print
Biggest part: resource_load_delay, 2863 msandThe four p75s add up to 4645 ms, not 4588.
Two things to take away. First, the field agrees with the frames: the photo is asked for late. Chrome's team writes that a high resource load delay means the image "is discovered late by the browser". Here, slider.js waits for the CMS before it adds the photo. Second, the parts don't add up to the LCP p75. Each is the p75 of its own part, so the docs say to use them to rank the parts, not as an exact split.
Round trips
round_trip_time is how long a message takes to reach a server and come back. Chrome estimates it from recent connections, as navigator.connection.rtt does. It has three bins: under 75 ms, 75 to 275 ms, and 275 ms or more. Chrome's team calls them low, medium and high, not good and poor. For Leaf and Kettle's phone visits, the shares were 0.1756, 0.622 and 0.2024, with a p75 of 250 ms.
The docs stress whose number this is: it's "a measure of the users to your site", not of the site. Why it matters: if it climbs while your site stays the same, your visitors changed, and your other metrics can get worse with them.
Navigation types
navigation_types says how each page load started, as fractions:
navigate: an ordinary load.navigate_cache: the HTML came from the HTTP cache.reload: the visitor reloaded.restore: the page loaded again after a browser restart, or after its tab was removed to save memory.back_forward: Back or Forward loaded the page again.back_forward_cache: Back or Forward showed it straight from the back/forward cache.prerender: the page was loaded in advance, before the visitor asked.
Every visit the course made was a fresh load in a new browser, so Leaf and Kettle's answer is navigate: 1 and 0 for the rest. On a real site, a big back_forward share next to a small back_forward_cache share means pages are missing the cache from The back/forward cache.
One limit: navigation types and round trips are metrics, not dimensions. A dimension, like the form factor, splits the other numbers. So you can't ask for the LCP of back/forward loads only, or of slow networks only.
Trends with the History API
Back to Ravi's puzzle. His fix went live on February 1. Why did CrUX keep saying 0.17?
The History API answers the same question as the CrUX API, for many weeks at once. You send the same key and the same body to another address, records:queryHistoryRecord. The body can have one more field:
collectionPeriodCount: how many weekly windows you want, from 1 to 40. Leave it out, and you get 25.
Each collection period is one 28-day window. The API is updated every Monday, with data up to the Saturday before. Each period ends one week after the one before. So two neighbouring periods share three of their four weeks.
A café keeps a board of the last four weeks of orders. Every Monday morning, the owner takes a photo of it. Between two photos, only one week changes: the oldest week comes off, and last week goes on. A new dish needs four photos before every week on the board has it.
- In real life: The board: the last four weeks of orders
- In CrUX: One collection period: 28 days
- In real life: Each Monday's photo of the board
- In CrUX: One entry in each History API array
- In real life: One week off the board, one week on
- In CrUX: Periods a week apart, sharing three weeks
- In real life: Four photos before a new dish fills the board
- In CrUX: Four periods before a fix covers a whole window
Here is what changed for phone visitors to the Mint tea page:
Ravi asked on Monday, March 2, with collectionPeriodCount: 5. Here is the answer for the page's CLS on phones:
// The History API's answer for the Mint tea page on phones, shortened to CLSconst cls = { histogramTimeseries: [ { start: "0.00", end: "0.10", densities: [0, 0.2584, 0.5114, 0.7529, 1] }, { start: "0.10", end: "0.25", densities: [1, 0.7416, 0.4886, 0.2471, 0] }, { start: "0.25", densities: [0, 0, 0, 0, 0] }, ], percentilesTimeseries: { p75s: ["0.17", "0.17", "0.17", "0.00", "0.00"] },};const lastDays = ["Jan 31", "Feb 7", "Feb 14", "Feb 21", "Feb 28"]; lastDays.forEach((day, i) => { const good = Math.round(cls.histogramTimeseries[0].densities[i] * 100); console.log(`To ${day}: ${good}% good, p75 ${cls.percentilesTimeseries.p75s[i]}`);}); - Lines 4 to 6 are
histogramTimeseries: the same three bins, but each hasdensities, one per period, oldest first. - Line 8 is
percentilesTimeseries.p75s: one p75 per period. In the full answer, acollectionPeriodslist gives each period's dates, in the same order. - Line 10 holds each period's last day.
- Lines 12 to 15 print one line per period, from
To Jan 31: 0% good, p75 0.17toTo Feb 28: 100% good, p75 0.00.
Every phone visit after February 1 had a good CLS. Each Monday, one more of those weeks came into the window, and one old week dropped out. So the good share climbed a step a week: 0, 26, 51, 75, then 100%. A p75 turns good only when at least 3 in 4 page loads are good. That happened in the window to February 21, three weeks after the fix.
Why it matters: after a fix, the p75 can take three or four weeks to move. The good share shows the change from the first week.
The whole site moved sooner. On phones, its CLS p75 was 0.17 in the window to January 31, and 0.00 in every window after. Before the fix, just over a quarter of the site's phone loads jumped: its good share was 0.7351. One fixed week lifted it to 0.8036, over 3 in 4. Why it matters: a site can look fixed while one page still fails. To check a fix on one page, ask for that page's URL.
Sometimes a period has too little data. Then its densities come back as "NaN" and its p75 as null. Pages fall in and out of CrUX, so a page's history can have gaps.
CrUX Vis: the history as charts
Reading arrays is slow. CrUX Vis, at cruxvis.withgoogle.com, draws the History API's answers as charts. Type an origin or a URL and press Go. If you leave out https://, it adds it for you. You can bookmark and share the address of the charts.
It has six pages: Core Web Vitals, Loading Performance, Interactivity, Visual Stability, Ad Metrics and All Metrics. The Loading Performance page has the LCP resource types, subparts, round trips and navigation types too. Each chart covers the past 40 weeks: one point per 28-day window, with a new point each Monday. Its controls switch four things:
- Origin data or URL data.
- The device: Phone, Desktop, Tablet, or all of them.
- The time periods shown.
- The display: the 75th percentile, the distributions, or both.
Chrome's team recommends it over the older CrUX Dashboard. It can't draw a site that isn't in CrUX, and a URL can be missing even when its origin is there. It has no settings beyond its controls. For any other chart, call the History API yourself.
Here is a small chart drawn the same way from Ravi's five periods. Switch to the whole site, then to Desktop:
The p75 first turned good in the window to Feb 21: 0.00.
Querying CrUX on BigQuery
The APIs answer one site at a time, for 40 weeks at most. To look at many sites, or further back, use BigQuery. CrUX keeps a table there for every month since 2017, with every origin in CrUX.
To use it, create a Google Cloud project with billing set up. Then open the chrome-ux-report project in BigQuery. Queries are free up to BigQuery's free tier, which renews every month and covers the first 1 TB of data read.
Each month gets a table, and each table follows four rules:
- Its name is
chrome-ux-report.all.YYYYMM, like202601for January. - It holds the last 28 days of its month.
- It comes out on the second Tuesday of the next month.
- It has origins only: no single pages, and no LCP subparts or resource types.
So Ravi's January table holds weeks 1 to 4, and came out on February 10. His February table holds weeks 5 to 8. Next to the monthly tables, the materialized dataset has summary tables. They have one row per origin and month, with shares and rough p75s already worked out. device_summary splits each row by form factor.
A summary table, month by month
The quickest question asks a summary table. Here is Ravi's CLS, month by month:
SELECT yyyymm, small_cls, medium_cls, large_clsFROM `chrome-ux-report.materialized.metrics_summary`WHERE date >= '2026-01-01' AND origin = 'https://leafandkettle.example'ORDER BY yyyymm - Lines 2 to 5 pick the month and three CLS shares: under 0.1, 0.1 to 0.25, and over 0.25.
- Line 7 names the summary table.
- Line 9 filters on
date, the first day of each month. The table is split by that date, so BigQuery only reads the months you ask for. - Line 10 picks the site, and lines 11 and 12 sort the months.
It returns two rows: 202601 with a small_cls of 0.8146, and 202602 with 1. Monthly tables don't overlap. So January holds only weeks from before the fix, and February only weeks after it. Why it matters: a month-to-month table gives a clean before and after. But February's table only came out on March 10.
A raw table, bin by bin
A monthly table in all has one row per origin and form factor. Each metric is a histogram of many small bins. Each bin's density is a share of all the origin's page loads that month: phones and computers together.
Asha and Ravi share one cake. Some of the slices on Asha's plate have cherries. Those slices are a share of the whole cake. To say what share of her slices had cherries, divide by her slices, not by the whole cake.
- In real life: The whole cake
- In BigQuery: All of an origin's page loads in one month
- In real life: The slices on Asha's plate
- In BigQuery: The bins in the origin's phone row
- In real life: Asha's slices with cherries
- In BigQuery: The phone row's good bins
- In real life: Cherry slices out of Asha's slices
- In BigQuery: Good phone loads out of all phone loads
SELECT form_factor.name AS device, ROUND(SUM(IF(bin.start < 2500, bin.density, 0)) / SUM(bin.density), 4) AS good_shareFROM `chrome-ux-report.all.202602`, UNNEST(largest_contentful_paint.histogram.bin) AS binWHERE origin = 'https://leafandkettle.example'GROUP BY deviceORDER BY device - Line 2 names each row's form factor.
- Line 3 adds up the good bins' densities, those that start below 2,500 ms. It divides them by all of that form factor's densities, and rounds to 4 decimal places.
- Line 6 is
UNNEST. It turns each row's list of bins into rows of their own, one per bin. - Line 8 picks the site. Lines 9 and 10 give one answer per form factor.
It returns desktop with 1, and phone with 0.5238. Every computer load had a good LCP, and just over half of the phone loads did. CrUX's own sample query for devices divides the same way: by the sum of each device's shares. Why it matters: forget to divide, and every form factor's share looks smaller than it is.
Run these queries, and two more, on the course's tables:
SELECT
yyyymm,
small_cls,
medium_cls,
large_cls
FROM
`chrome-ux-report.materialized.metrics_summary`
WHERE
date >= '2026-01-01' AND
origin = 'https://leafandkettle.example'
ORDER BY
yyyymm
| yyyymm | small_cls | medium_cls | large_cls |
|---|---|---|---|
| 202601 | 0.8146 | 0.1854 | 0 |
| 202602 | 1 | 0 | 0 |
Each row is one group the query asked for. Shares are between 0 and 1: 0.5 means half the page loads.
Comparing with competitors
Ravi has one more question: is Teapot Lane, the tea shop across town, faster? CrUX is public. With your key, you can ask about any origin in it, yours or not.
The API takes one origin or URL per request. So Ravi asks twice on Monday, March 2, once for each shop:
// LCP p75 on Monday, March 2: all page loads, then phones and computersconst shops = [ { name: "Leaf and Kettle", all: 3520, phones: 3900, computers: 184 }, { name: "Teapot Lane", all: 376, phones: 764, computers: 208 },]; for (const shop of shops) { console.log(`${shop.name}: all ${shop.all} ms, phones ${shop.phones} ms, computers ${shop.computers} ms`);} - Lines 3 and 4 hold each shop's LCP p75: for all page loads, then phones only, then computers only.
- Line 8 prints one line per shop:
Leaf and Kettle: all 3520 ms, phones 3900 ms, computers 184 msTeapot Lane: all 376 ms, phones 764 ms, computers 208 ms
Two cafés compare their delivery times. Most of one café's customers live next door, so its overall time looks great. To see which café is really quicker, compare deliveries to the same street.
- In real life: Most orders from next door
- In CrUX: Most page loads from computers on fast networks
- In real life: The time for all deliveries together
- In CrUX: The p75 for all form factors together
- In real life: Deliveries to the same street
- In CrUX: The p75 for one form factor
- In real life: How far the customers live
- In CrUX: form_factors and round_trip_time
Overall, Teapot Lane looks more than nine times faster: 376 ms against 3,520. Now read who visits. form_factors says phones made 0.7 of Leaf and Kettle's page loads, and only 0.3 of Teapot Lane's. Teapot Lane's round trips had a p75 of 100 ms, against 200 ms for Leaf and Kettle. Most of its visitors use computers, on faster networks.
Then compare like with like. On computers, Leaf and Kettle is a little faster: 184 ms against 208. On phones, Teapot Lane is about five times faster: 764 ms against 3,900. Most of that gap is the home page. Teapot Lane's has its first photo in the HTML, the capstone's first fix, and its p75 on phones was 776 ms, against 4,692.
Why it matters: the overall number mixed a real gap with a different crowd. Phone to phone, Ravi learns what to fix: his home page.
BigQuery compares many shops in one query. Change the device query's WHERE to a list of origins, and group by origin too:
SELECT origin, form_factor.name AS device, ROUND(SUM(IF(bin.start < 2500, bin.density, 0)) / SUM(bin.density), 4) AS good_shareFROM `chrome-ux-report.all.202602`, UNNEST(largest_contentful_paint.histogram.bin) AS binWHERE origin IN ('https://leafandkettle.example', 'https://teapotlane.example')GROUP BY origin, deviceORDER BY device, origin - Line 9 lists both origins. Line 11 groups the rows by origin, then by device.
- It returns four rows. On desktops, both shops get
1. On phones, Leaf and Kettle gets0.5238and Teapot Lane gets1.
A fair comparison follows four rules:
- Compare one form factor with the same form factor.
- Compare the same days: the same day's API answers, or the same monthly table.
- Read
form_factorsandround_trip_timebefore you blame the site. They describe the visitors. - Compare with several sites like yours, about ten, as Performance budgets suggested.
Which tool answers this?
Each row is one of the four doors. Read across to see what it gives, how often it changes, and what it covers:
| Tool | What does it give? | How often does it change? | Pages or whole sites? |
|---|---|---|---|
| The CrUX API | The latest 28 days, as one record. | Every day. | Both: an origin or one URL. |
| The History API | Up to 40 weekly 28-day windows, as lists. | Every Monday. | Both: an origin or one URL. |
| CrUX Vis | Charts of the History API's last 40 weeks. | Every Monday. | Both: an origin or one URL. |
| BigQuery | A table for every month since 2017, with every origin. | Once a month, on the second Tuesday. | Whole sites only. |
Now sort Ravi's questions by the tool that answers them best:
- A script checks the Mint tea page's latest CLS on phones every morning
- A script must notice when CrUX has no tablet data for a page
- Store the site's LCP p75 for each of the last 25 weeks
- In code, follow the Mint tea page week by week since the fix
- Show the team a chart of INP over the last 40 weeks, with no code
- See a URL's good, needs improvement and poor shares week by week, on a chart
- Rank 500 tea shops by their LCP in one query
- Find the site's LCP p75 in each country
- See how the site's LCP changed month by month over three years
Sort each question by the tool that answers it best.
Common mix-ups
- "The CrUX API's numbers are for today." No. They cover the last 28 days, and run about two days behind.
- "A fix shows in the next History API period." No. That period still holds three weeks from before the fix.
- "The four subpart p75s add up to the LCP p75." No. On the home page they came to 4,645 ms, and the LCP p75 was 4,588 ms.
- "The API sends CLS as a number." No. It sends text with two decimal places, like "0.17".
- "A 404 means the API is broken." No. It means CrUX has no data for that question.
- "In BigQuery, a phone row's densities add up to 1." No. All of an origin's rows add up to 1 together.
- "A better overall p75 means a faster site." No. The visitors may differ. Compare phones with phones.
Practice exercises
Answer first, then use the hints.
Ravi sends the same request on Monday, March 2. What does the last line print now?
// CrUX's answer on Monday, March 2
const answer = {
record: {
key: { formFactor: "PHONE", origin: "https://leafandkettle.example" },
metrics: {
largest_contentful_paint: {
histogram: [
{ start: 0, end: 2500, density: 0.5238 },
{ start: 2500, end: 4000, density: 0.2649 },
{ start: 4000, density: 0.2113 },
],
percentiles: { p75: 3900 },
},
},
collectionPeriod: {
firstDate: { year: 2026, month: 2, day: 1 },
lastDate: { year: 2026, month: 2, day: 28 },
},
},
};
const lcp = answer.record.metrics.largest_contentful_paint;
console.log(`p75: ${lcp.percentiles.p75} ms`);
console.log(`Good: ${(lcp.histogram[0].density * 100).toFixed(1)}% of page loads`);
Good: 52.4% of page loads. Line 8's density is now 0.5238: the window is February 1 to 28. Ravi's fix was for CLS, so LCP barely moved.
Here are the same metrics for Teapot Lane's home page on phones. What does the first line print?
// Teapot Lane's home page on phones: the LCP p75, and each image subpart's p75
const lcpP75 = 776;
const parts = {
time_to_first_byte: 198,
resource_load_delay: 37,
resource_load_duration: 564,
element_render_delay: 20,
};
const [biggest] = Object.entries(parts).sort((a, b) => b[1] - a[1]);
const sum = Object.values(parts).reduce((total, ms) => total + ms, 0);
console.log(`Biggest part: ${biggest[0]}, ${biggest[1]} ms`);
console.log(`The four p75s add up to ${sum} ms, not ${lcpP75}`);
Biggest part: resource_load_duration, 564 ms. Teapot Lane's first photo is in the HTML, so the browser asks for it at once: its load delay is only 37 ms. Now the download is the longest wait.
In the CrUX API playground, what was the Shop page's LCP p75 on desktops on March 2, in ms?
156 ms: good. On computers, the Shop page's photos are small copies, 360 pixels wide, and load quickly.
In the small CrUX Vis, what was the whole site's INP p75 on phones in the window ending February 28, in ms?
192 ms: good, just under the 200 ms limit. It came down from 232 ms in the window to January 31.
The CrUX API calls CLS cumulative_layout_shift. What is it called in BigQuery's raw tables?
layout_instability.cumulative_layout_shift. In the raw tables, CLS sits inside a record called layout_instability, so a query unnests layout_instability.cumulative_layout_shift.histogram.bin.
Ravi wants the share of January's phone loads with a good LCP. His query returns 0.3771, but the API said 53.9%. What should it return, as BigQuery shows it?
SELECT
ROUND(SUM(bin.density), 4) AS good_phone_share
FROM
`chrome-ux-report.all.202601`,
UNNEST(largest_contentful_paint.histogram.bin) AS bin
WHERE
origin = 'https://leafandkettle.example' AND
form_factor.name = 'phone' AND
bin.start < 2500
SELECT
form_factor.name AS device,
ROUND(SUM(IF(bin.start < 2500, bin.density, 0)) / SUM(bin.density), 4) AS good_share
FROM
`chrome-ux-report.all.202601`,
UNNEST(largest_contentful_paint.histogram.bin) AS bin
WHERE
origin = 'https://leafandkettle.example'
GROUP BY
device
ORDER BY
device
0.5387. Each density is a share of all of January's page loads, computers too. So the phone row's good bins came to 0.3771 of everything: 0.7 phones times 0.5387 good. Divide by all the phone bins, as the device query does.
Check your understanding
For each question, ask which door it uses, and which 28 days the number covers.
Question 1 of 7What does this version of the 404 example print?
Read the code, then predict// The same function, with another answer const response = { status: 200, body: { record: { key: { origin: "https://teapotlane.example" } } } }; function recordOf(response) { if (response.status === 404 && response.body.error?.status === "NOT_FOUND") return null; return response.body.record; } console.log(recordOf(response)?.key.origin ?? "No CrUX data for this question");Choose an answer to see the explanation.
Question 2 of 7Ravi's fix went live on February 1. Why did the period ending February 7 still give the Mint tea page a CLS p75 of 0.17?
Choose an answer to see the explanation.
Question 3 of 7Which request body gets you the form_factors fractions?
Choose an answer to see the explanation.
Question 4 of 7What does round_trip_time describe?
Choose an answer to see the explanation.
Question 5 of 7Where can you get the LCP image subparts?
Choose an answer to see the explanation.
Question 6 of 7In a BigQuery monthly table, what do an origin's densities add up to?
Choose an answer to see the explanation.
Question 7 of 7Teapot Lane's overall LCP p75 is far better than Leaf and Kettle's. What should Ravi compare before calling it faster?
Choose an answer to see the explanation.
Key takeaways
- The CrUX API answers a POST with a record: its key, its metrics and its 28-day collection period. A 404 means no data.
- Its histograms have three bins and a p75. CLS comes as text, like "0.17".
- LCP resource types and image subparts point at the slow part of LCP. The subparts rank the parts; they don't add up.
- Round trips describe your visitors' networks, not your site. Navigation types say how page loads started.
- The History API gives up to 40 weekly windows of 28 days. A fix needs four weeks to fill a window.
- CrUX Vis draws the History API's answers. BigQuery keeps a table per month for every origin.
- Compare competitors one form factor at a time, over the same days.
Remember the one-liner.
The API gives the latest 28 days, the History API one window a week, CrUX Vis draws them, and BigQuery keeps every month for every site.
Sources
The facts on this page come from these docs and source code:
- CrUX API, Chrome UX Report docs.
- How to use the CrUX API, Chrome UX Report docs.
- CrUXManager.ts: how DevTools asks the CrUX API, Chrome DevTools source code.
- About PageSpeed Insights: the Good, Needs Improvement and Poor bands, Google for Developers.
- Metrics, Chrome UX Report docs.
- LCP image subparts and RTT now available in CrUX, Chrome for Developers blog.
- Navigation types now available in CrUX, Chrome for Developers blog.
- CrUX History API, Chrome UX Report docs.
- How to use the CrUX History API, Chrome UX Report docs.
- CrUX Vis, Chrome UX Report docs.
- CrUX Dashboard deprecation, Chrome for Developers blog.
- CrUX on BigQuery, Chrome UX Report docs.
- How to use the CrUX BigQuery dataset, Chrome UX Report docs.
- CrUX tools: which days each tool covers, Chrome UX Report docs.
- 03-device-cwv.sql: Core Web Vitals by device, GoogleChrome/CrUX, source code.
- Dimensions, Chrome UX Report docs.
Coming next: The performance timeline, the first lesson of the next module. Chrome measures every CrUX metric inside the browser, and any page can measure the same things through browser APIs. You'll meet the one those APIs are all built on.