completefrontend
Open lab My progress
THE WEB PERFORMANCE FIELD GUIDE

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.

By the end, you can
  • 01
    Ask 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.
  • 02
    Follow 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.
  • 03
    Query 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:

Five weeks of CrUX's answerPop out in the code editor (opens in a new tab)JavaScript
// 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 is Feb 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.
Real-life analogyA weather service with four counters

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:

Eight weeks of visits to Leaf and Kettle, from January 4 to February 28. Weeks 1 to 4 come before the fix, weeks 5 to 8 after it. The CrUX API, asked on February 2, covers weeks 1 to 4. The History API, asked on March 2, gives five 28-day windows, each one week later than the one before. BigQuery has a January table for weeks 1 to 4 and a February table for weeks 5 to 8.Jan 4Jan 11Jan 18Jan 25Feb 1Feb 8Feb 15Feb 22Weeksbefore the fixafter the fixCrUX APIon Feb 2History APIon Mar 2BigQuerya table a month202601202602
Each bar under the weeks is a 28-day window. The tools differ in when you read them and how many windows they give. Shaded: the four weeks after Ravi's fix.

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.
The main idea

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:

  • origin or url: the whole site, or one page. You give one of them, never both.
  • formFactor: PHONE, DESKTOP or TABLET. 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 for the whole site's LCP on phonesJavaScript
// 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:

The answer: one recordPop out in the code editor (opens in a new tab)JavaScript
// 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's density is 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 ms and Good: 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:

No data is a 404Pop out in the code editor (opens in a new tab)JavaScript
// 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 an error whose status is NOT_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: http instead of https, or a missing www.
  • 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:

Playground: ask the CrUX API
The request bodyJSON
{
  "origin": "https://leafandkettle.example",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "interaction_to_next_paint",
    "cumulative_layout_shift"
  ]
}
The answer200 OK
{
  "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 }
    }
  }
}
Try it yourself
A record for the whole site, on phones

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.

The answers lay out the course's own visits to Leaf and Kettle the way the CrUX API reference lays out a record. The request asks for the three Core Web Vitals.

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:

One load of Leaf and Kettle's home page on Asha's phone. At 0 ms, Asha opens the home page: a blank screen. At 564 ms, the first byte arrives: a blank screen. At 3,747 ms, the photo is asked for: the page with an empty grey slider. At 5,927 ms, the photo's last byte arrives: the photo, drawn bit by bit as it downloaded. At 5,940 ms, the photo is painted: LCP: the whole photo. Between the screens are the four parts: TTFB 564 ms, load delay 3,183 ms, load duration 2,180 ms, render delay 10 ms.0 msblankAsha opensthe home page564 msblankthe first bytearrives3,747 msThe home page at 1,918 ms: the page with an empty grey sliderthe photo isasked for5,927 msThe home page at 5,389 ms: the photo, drawn bit by bit as it downloadedthe photo's lastbyte arrives5,940 msThe home page at 5,940 ms: the whole photothe photo ispainted: LCPTTFB564 msload delay3,183 msload duration2,180 msrender delay10 ms
One load of the home page on Asha's phone, from the capstone's lab. The last three screens are real frames Chrome captured. The screens are evenly spaced, not to scale. The longest part is the load delay, 3.2 s: the photo isn't asked for until slider.js has the CMS's list of slides. Until then, the slider stays grey. Chrome draws the photo bit by bit as its bytes come in, so it's almost all there before the last byte.

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:

Which part of the home page's LCP is slow?Pop out in the code editor (opens in a new tab)JavaScript
// 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 ms and The 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.

Real-life analogyA board of the last four weeks, photographed every Monday

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:

The Mint tea page on Asha's phone, before and after Ravi's fix. Before the fix, at 1.3 s: the photo is in. Before the fix, at 4.0 s: reviews push it down. After the fix, at 1.3 s: room kept for reviews. After the fix, at 4.0 s: the photo stays put.Weeks 1 to 4: before the fixWeeks 5 to 8: with the fixThe Mint tea page at 1.3 s: the photo is in1.3 sthe photo is inThe Mint tea page at 4.0 s: reviews push it down4.0 sreviews push it downThe Mint tea page at 1.3 s: room kept for reviews1.3 sroom kept for reviewsThe Mint tea page at 4.0 s: the photo stays put4.0 sthe photo stays put
Real frames from the capstone's lab loads of the Mint tea page. Before the fix, the reviews box arrives at about 4.0 s and pushes the photo down: a layout shift of 0.171. With the fix, the space is kept from the start, and nothing moves. The fix went live on February 1.

Ravi asked on Monday, March 2, with collectionPeriodCount: 5. Here is the answer for the page's CLS on phones:

Five periods in one answerPop out in the code editor (opens in a new tab)JavaScript
// 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 has densities, one per period, oldest first.
  • Line 8 is percentilesTimeseries.p75s: one p75 per period. In the full answer, a collectionPeriods list 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.17 to To 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:

Playground: a small CrUX Vis
CLS, Mint tea, Phonewindows ending on these Saturdays
0% good26% good51% good75% good100% good
Jan 31Feb 7Feb 14Feb 21Feb 28
Try it yourself
CLS, Mint tea, Phone

The p75 first turned good in the window to Feb 21: 0.00.

Drawn from the History API's five periods for the course's own visits. Like CrUX Vis, it shows one metric: a point per 28-day window, with the p75 or the three bands.

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, like 202601 for 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:

CLS by month, from metrics_summarySQL
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.

Real-life analogySlices of one cake

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
Good LCP, by form factorSQL
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:

Playground: run a query
CLS by monthSQL
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
Query results4 columns
yyyymmsmall_clsmedium_clslarge_cls
2026010.81460.18540
202602100
Try it yourself
2 rows

Each row is one group the query asked for. Shares are between 0 and 1: 0.5 means half the page loads.

Each query runs on the course's own visits, laid out as CrUX's BigQuery tables lay out their data. There's one row per origin and form factor, with the LCP histogram in 100 ms bins.

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:

Two shops, three waysPop out in the code editor (opens in a new tab)JavaScript
// 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 ms
    • Teapot Lane: all 376 ms, phones 764 ms, computers 208 ms
LCP p75 on March 2. All page loads: Leaf and Kettle 3,520 ms, Teapot Lane 376 ms. Phones: Leaf and Kettle 3,900 ms, Teapot Lane 764 ms. Computers: Leaf and Kettle 184 ms, Teapot Lane 208 ms. Phones made 70% of Leaf and Kettle's page loads and 30% of Teapot Lane's.Leaf and KettleTeapot LaneAll page loads3,520 ms376 msPhones3,900 ms764 msComputers184 ms208 msgood up to 2,500 ms
Each bar is one shop's LCP p75, to scale. The dashed line is the good limit, 2,500 ms. Phones made 70% of Leaf and Kettle's page loads, but only 30% of Teapot Lane's. So Teapot Lane's "all" bar sits close to its computers.
Real-life analogyTwo cafés' delivery times

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:

Both shops, by form factorSQL
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 gets 0.5238 and Teapot Lane gets 1.

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_factors and round_trip_time before 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:

The four ways to read CrUX yourself
ToolWhat does it give?How often does it change?Pages or whole sites?
The CrUX APIThe latest 28 days, as one record.Every day.Both: an origin or one URL.
The History APIUp to 40 weekly 28-day windows, as lists.Every Monday.Both: an origin or one URL.
CrUX VisCharts of the History API's last 40 weeks.Every Monday.Both: an origin or one URL.
BigQueryA 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:

Which tool answers this?
  • 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
Try it yourself
0 of 9 correct

Sort each question by the tool that answers it best.

Choose a category for every card. You can change an answer at any time; Reset clears them all.

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.

Exercise 1 · Warm-upA month later

Ravi sends the same request on Monday, March 2. What does the last line print now?

Starter codePop out in the code editor (opens in a new tab)JavaScript
// 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`);

Answer, then press Check. Spacing and letter case don’t matter.

    Exercise 2 · Warm-upTeapot Lane's home page

    Here are the same metrics for Teapot Lane's home page on phones. What does the first line print?

    Starter codePop out in the code editor (opens in a new tab)JavaScript
    // 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}`);
    

    Answer, then press Check. Spacing and letter case don’t matter.

      Exercise 3 · PracticeThe Shop page on computers

      In the CrUX API playground, what was the Shop page's LCP p75 on desktops on March 2, in ms?

      Answer, then press Check. Spacing and letter case don’t matter.

        Exercise 4 · PracticeThe whole site's INP

        In the small CrUX Vis, what was the whole site's INP p75 on phones in the window ending February 28, in ms?

        Answer, then press Check. Spacing and letter case don’t matter.

          Exercise 5 · ChallengeCLS in BigQuery

          The CrUX API calls CLS cumulative_layout_shift. What is it called in BigQuery's raw tables?

          Answer, then press Check. Spacing and letter case don’t matter.

            Exercise 6 · ChallengeFix the phone query

            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?

            Starter codeSQL
            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
            

            Answer, then press Check. Spacing and letter case don’t matter.

              Check your understanding

              For each question, ask which door it uses, and which 28 days the number covers.

              The CrUX API, history, and BigQuery quiz · 7 questionsScore: first tries count
              1. Question 1 of 7What does this version of the 404 example print?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // 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.

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

              3. Question 3 of 7Which request body gets you the form_factors fractions?

                Choose an answer to see the explanation.

              4. Question 4 of 7What does round_trip_time describe?

                Choose an answer to see the explanation.

              5. Question 5 of 7Where can you get the LCP image subparts?

                Choose an answer to see the explanation.

              6. Question 6 of 7In a BigQuery monthly table, what do an origin's densities add up to?

                Choose an answer to see the explanation.

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

              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.

              CompleteFrontend Clear concepts. Working examples.