The Chrome UX Report API gives low-latency access to aggregated Real User Metrics (RUM) from the Chrome User Experience Report.
Common use case
The Chrome UX Report API allows for the querying of user experience metrics for a specific URI like "Get metrics for the https://example.com
origin."
Data model
Record
A discrete piece of information about a page, or site. A record can have data that is specific for an identifier and for a specific combination of dimensions. A record can contain data for one or more metrics.
Identifiers
Identifiers specify what records should be looked up. In the Chrome UX Report these identifiers are webpages and websites.
Origin
When the identifier is an origin
all data present for all pages in that origin are aggregated together. For example, say the http://www.example.com
origin had pages as laid out by this sitemap:
http://www.example.com
http://www.example.com/foo.html
http://www.example.com/bar.html
This would mean that when querying the Chrome UX Report with the origin
set to http://www.example.com
, data for http://www.example.com/
, http://www.example.com/foo.html
, and http://www.example.com/bar.html
would be returned because those are all pages under that origin.
URLs
When the identifier is a url
only data for that specific url will be returned. Looking again to the http://www.example.com
origin sitemap:
http://www.example.com
http://www.example.com/foo.html
http://www.example.com/bar.html
If the identifier is set to url
with the value of http://www.example.com/foo.html
, only data for that page will be returned.
Dimensions
Dimensions identify a specific group of data that a record is being aggregated against, e.g. a form factor of Mobile
indicates that the record contains information about loads that took place on a mobile device. Each dimension will have a certain number of values, and implicitly the lack of specifying that dimension will mean that the dimension is aggregated over all values. For example, specifying no form factor indicates that record contains information about loads that took place on any form factor.
Form Factor
The device class that the end-user used to navigate to the page. This is a general class of device split into Mobile
, Tablet
, and Desktop
.
Metric
See metrics for more info about the kinds of metrics included in the CrUX dataset.
Metrics are expressed in a histogram, which represents the percent of users that experienced a metric with that value proportionally to all.
A simple three bin histogram for metric "ExampleMetric" looks like this.
{ "histogram": [ { "start": 0, "end": 1000, "density": 0.38179089544772343 }, { "start": 1000, "end": 3000, "density": 0.49904952476238057 }, { "start": 3000, "density": 0.11915957978989571 } ], }
This data indicates that 38.2% of users experience an ExampleMetric value between 0ms and 1000ms. The units of ExampleMetric are not contained in this histogram, in this case we will assume milliseconds.
Additionally, 49.9% of users experience an ExampleMetric value between 1000ms and 3000ms, and 11.9% of users experience an ExampleMetric value greater than 3000ms.
Metrics will also contain percentiles that can be useful for additional analysis.
{ "percentiles": { "p75": 2063 }, }
These percentiles can show specific metric values at the given percentile for that metric. They are based off the full set of available data and not the final binned data, so they do not necessarily match an interpolated percentile that is based off the final binned histogram.
Metric value types
CrUX API Metric Name | Data Type | Metric Units | web.dev Docs |
---|---|---|---|
first_contentful_paint |
int |
milliseconds | fcp |
largest_contentful_paint |
int |
milliseconds | lcp |
cumulative_layout_shift |
double encoded as string |
unitless | cls |
first_input_delay |
int |
milliseconds | fid |
BigQuery metric name mapping
CrUX API Metric Name | BigQuery Metric Name |
---|---|
first_contentful_paint |
first_contentful_paint |
largest_contentful_paint |
largest_contentful_paint |
cumulative_layout_shift |
layout_instability.cumulative_layout_shift |
first_input_delay |
first_input.delay |
Data pipeline
The rolling average
The data in the Chrome UX Report is a 28-day rolling average of aggregated metrics. This means that the data presented in the Chrome UX Report at any given time is actually data for the past 28 days aggregated together.
This is similar to how the CrUX dataset on BigQuery aggregates monthly reports.
Daily updates
Data is updated daily around 04:00 UTC. There is no SLO for update times; it is run on a best effort basis everyday.