Most teams check real-user performance the way they check the weather: someone runs PageSpeed Insights when a stakeholder asks, screenshots the result, and everyone moves on. That is a spot check of a moving aggregate, and it answers neither of the questions that matter — is this getting better or worse, and did the thing we shipped change it?
The Chrome UX Report (CrUX) API answers both, for free, for any sufficiently trafficked public origin — including ones you do not own.
What the CrUX API actually returns
CrUX is Google's dataset of field measurements collected from opted-in Chrome users. Google documents that the API serves a rolling 28-day aggregation, updated daily, at two levels of granularity: individual URLs and whole origins. For each metric — LCP, INP, CLS, plus diagnostics like TTFB and FCP — you get the 75th-percentile value and a histogram of the good / needs-improvement / poor distribution, optionally split by form factor.
This is the same family of data that feeds the Core Web Vitals report in Search Console, but exposed programmatically, refreshed daily rather than viewed through a UI, and queryable for any origin that clears the traffic threshold.
The one structural catch: an entry exists only when there is enough traffic. Google does not publish the eligibility threshold. Many individual URLs on mid-sized sites will return no data, while the origin-level record almost always will. Plan around that: origin-level for the trend line, URL-level for the pages that have the volume to support it.
Why a trend line beats a spot check
A single reading of a 28-day rolling window cannot tell you when something changed, only that it eventually did. If you deploy a regression today, the p75 drifts for weeks as bad days replace good days in the window. Checked once a month, that drift is invisible; you see two numbers and no shape.
Pulled daily and stored, the same data shows an inflection point. A 28-day window means a step change in real performance appears as a ramp starting the day it shipped — so the start date of the ramp is your diagnostic, and you can line it up against your deploy log. This is the entire trick: the API's smoothing destroys timing information within any single response, and daily collection recovers it.
Pulling the data
The endpoint takes a POST with an API key from any Google Cloud project:
curl -s "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$KEY" \
-H 'Content-Type: application/json' \
-d '{"origin": "https://example.com", "formFactor": "PHONE"}'Swap origin for url to query a specific page. The response contains, per metric, the histogram densities and the p75 value. A minimal collector is a scheduled job that loops over a list of origins and URLs, flattens the response into rows — date, target, form factor, metric, p75, plus the three histogram densities — and appends them to a table. That is an afternoon of work in any language, and it is the difference between owning your performance history and re-requesting a snapshot forever.
Google also documents a companion History API (records:queryHistoryRecord) that returns a series of weekly snapshots in one call. It is the fast way to backfill a chart before your own collection starts, with coarser, weekly resolution rather than the daily cadence you get by collecting yourself.
Monitoring competitors with the same loop
Nothing in the API restricts you to origins you control. Any public origin with sufficient Chrome traffic is queryable, which makes CrUX one of the few sources of field data about competitors — not what their site scores in a lab run you triggered, but what their real users experience.
Add competitor origins to the same collection loop and you get comparative trend lines: whether the gap between your p75 LCP and theirs is widening, whether their INP degraded after their last redesign, whether "everyone in the category got slower" (which usually points at a shared third-party script or a heavier ad stack, not your code). That context changes decisions. Being at 2.9s LCP means something different when the category leader sits at 1.8s than when everyone clusters at 3s.
The limits worth respecting
It is a biased sample by construction. Chrome users who opt into sync and usage reporting, on eligible platforms. Google documents the population; you cannot change it. Safari and Firefox users are absent entirely, which matters for iOS-heavy audiences — treat CrUX as the Chrome view, corroborated by your own RUM if you have it.
The 28-day window lags. Even collected daily, a fix takes weeks to fully wash through the aggregate. Do not judge a remediation as failed two days after shipping it.
No custom segmentation. Form factor and (at the origin level) country are the documented dimensions. No browser version, no logged-in versus logged-out, no traffic source. Questions at that resolution belong to your own RUM instrumentation, not CrUX.
Quotas are real but generous for this use. A daily loop over a few dozen targets sits comfortably inside them; hammering thousands of URLs per hour does not.
What to do
- Get an API key and pull your origin today, both form factors, and look at the histograms — the p75 alone hides a bimodal distribution.
- Stand up a daily collector for your origin, your top URLs by traffic, and two or three competitor origins. Append-only table; date, target, metric, p75, densities.
- Backfill with the History API so the chart has context from day one.
- Annotate deploys on the same timeline. The ramp-start-versus-deploy-log comparison is where this data earns its keep.
- Alert on direction, not thresholds. A p75 that worsens for seven consecutive days is a signal regardless of whether it has crossed a "poor" boundary yet — by the time it crosses, you have lost a month.