CrUX API

The CrUX API gives low-latency access to aggregated real-user experience data at page and origin granularity.

Try it!

Common use case

The CrUX API allows for the querying of user experience metrics for a specific URI like "Get metrics for the https://example.com origin."

CrUX API Key

Using the CrUX API requires a Google Cloud API key provisioned for Chrome UX Report API usage.

Acquiring and using an API key

Or create one in the Credentials page.

After you have an API key, your application can append the query parameter key=yourAPIKey to all request URLs.

The API key is safe for embedding in URLs; it doesn't need any encoding.

See Example queries.

Data model

This section details the structure of data in requests and responses.

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 CrUX 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, aggregated together, 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, for example a form factor of PHONE 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 PHONE, TABLET, and DESKTOP.

Metric

We report metrics as statistical aggregations, in histograms, percentiles, and fractions.

Floating point values are rounded to 4 decimal places (note that the cumulative_layout_shift metrics are doubles encoded as a string, so are not consider floats and are reported to 2 decimal places within the string).

Histogram

When metrics are expressed in a histogram, we show the percentages of page loads falling into particular ranges for that metric.

A three bin histogram for an example metric looks like this:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

This data indicates that for 38.18% of page loads, the example metric was measured between 0ms and 1,000ms. The units of the metric are not contained in this histogram, in this case we will assume milliseconds.

Additionally, 49.91% of page loads saw a metric value between 1,000ms and 3,000ms, and 11.92% saw a value greater than 3,000ms.

Percentiles

Metrics may also contain percentiles that can be useful for additional analysis. We report specific metric values at the given percentile for that metric. They are based on the full set of available data and not the final binned data, so they don't necessarily match an interpolated percentile that is based on the final binned histogram.

{
  "percentiles": {
    "p75": 2063
  }
}

In this example, at least 75% of page loads were measured with a metric value <= 2063.

Fractions

Fractions indicate the percentages of page loads that can be labeled in a particular way. In this case, the metric values are these labels.

For example, the form_factors metric consists of a fractions object listing the breakdown of form factors (or devices) that the given query covers:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

In this case, 3.77% of page loads were measured on a desktop, 2.88% on a tablet, and 93.35% on a phone, giving 100% in total.

Metric value types

BigQuery metric name mapping

Collection period

As of October 2022, the CrUX API contains a collectionPeriod object with firstDate and endDate fields representing the beginning and end dates of the aggregation window. For example:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month"