canonical: https://jentic.com/apis/googleapis.com/chromeuxreport

# Google Chrome UX Report API

The Chrome UX Report (CrUX) API exposes aggregated, anonymised real-user performance data collected from Chrome users for any sufficiently popular public origin or page URL. It returns Core Web Vitals - Largest Contentful Paint, Interaction to Next Paint, Cumulative Layout Shift - plus First Contentful Paint, Time to First Byte, and form-factor splits. Performance teams use it to track field metrics for sites they own and benchmark competitors' real-user performance.

## For AI agents

Query Chrome real-user performance data and Core Web Vitals (LCP, INP, CLS) for any public origin or URL with no instrumentation required.

## Scope

Does not run synthetic audits, instrument first-party analytics, or collect non-Chrome data - use for querying aggregated Chrome real-user Core Web Vitals only.

## Capabilities

- Query the latest 28-day Core Web Vitals for any public origin
- Query historical six-month time series of Core Web Vitals at the URL or origin level
- Filter results by form factor - phone, tablet, desktop
- Retrieve metric distributions across good, needs improvement, and poor buckets
- Benchmark a competitor origin against your own real-user performance

## Use cases

### Core Web Vitals Dashboard

Performance engineers ingest CrUX queryRecord results into a dashboard that shows LCP, INP, and CLS distributions for owned origins, broken down by form factor. The data is real-user field data - no synthetic or RUM instrumentation required - which makes it the canonical source for Google's Search ranking signal. Most teams refresh weekly because the dataset is calendar-aligned.

Example prompt: POST /v1/records:queryRecord with origin=https://example.com and metrics=["largest_contentful_paint","interaction_to_next_paint","cumulative_layout_shift"] and return p75 values.

### Historical Trend Analysis

Engineering managers track week-by-week regression and improvement of Core Web Vitals using queryHistoryRecord, which returns a six-month rolling time series. This shows whether shipped optimisations actually moved field metrics rather than only synthetic ones. The same call also surfaces form-factor splits so teams can isolate mobile-only regressions.

Example prompt: POST /v1/records:queryHistoryRecord with url=https://example.com/checkout and metric=largest_contentful_paint and return the six monthly p75 values.

### Competitor Benchmarking

Product teams query CrUX for competitor origins to benchmark their real-user performance. Because CrUX is public for any origin meeting the eligibility threshold, no special access is required. This is widely used in retail and media verticals to scope optimisation roadmaps against the market.

Example prompt: POST /v1/records:queryRecord for origin https://competitor.com formFactor=PHONE and return whether all three Core Web Vitals pass.

### AI Agent Performance Reporter via Jentic

An AI agent through Jentic runs an on-demand performance check - fetching the latest CrUX data for a list of owned origins, summarising which fail Core Web Vitals thresholds, and recommending where to invest. Jentic isolates the API key so the agent never sees the raw key value.

Example prompt: Through Jentic, search chromeuxreport_query_record, load schema, and execute it for origin https://example.com formFactor=PHONE and return p75 LCP.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/records:queryRecord | Query the latest 28-day CrUX record for an origin or URL |
| POST | /v1/records:queryHistoryRecord | Query rolling six-month CrUX history for an origin or URL |

## Key resources

- **Records (queryRecord)** — Query the latest 28-day CrUX dataset for an origin or URL
- **Records (queryHistoryRecord)** — Query the rolling six-month CrUX history for an origin or URL

## Why Jentic

- **Setup:** Wiring the Chrome UX Report API by hand means provisioning a Google Cloud API key, appending it to each request, and shaping the queryRecord and queryHistoryRecord payloads with the right form-factor filters yourself. Through Jentic you install once, import the Chrome UX Report API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Both operations take the origin or URL in the request body (/v1/records:queryRecord), so scope the agent to the operations it needs, such as queryRecord for current Core Web Vitals or queryHistoryRecord for trends. You choose those operations, and any not in that set are not included unless you add them.
- **Credential handling:** Your Google Cloud API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. The raw key string never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get core web vitals for an origin', and Jentic returns the records queryRecord operation with its parameter schema, including form-factor enums, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **PageSpeed Insights API** — Combines lab Lighthouse audits with CrUX field data for a single URL.
- **Google Search Console API** — Reports search performance and indexing status for owned properties.
- **Google Analytics Data API** — Reports first-party site analytics rather than aggregated Chrome field data.

## FAQ

### What authentication does the Chrome UX Report API use?

It uses a Google Cloud API key passed as the key query parameter. No OAuth is required since CrUX data is aggregated and public. Through Jentic, the API key is stored encrypted in your Jentic One instance and the agent calls CrUX without ever holding the raw key string.

### Can I query Core Web Vitals for any URL?

Only for URLs and origins that meet the CrUX eligibility threshold - enough Chrome real-user samples in the 28-day window. POST /v1/records:queryRecord with either the origin or url field; if the URL has insufficient data the API returns 404 and you should fall back to the origin-level query.

### What are the rate limits for the Chrome UX Report API?

Google enforces a default of 150 queries per minute per project on CrUX. Higher quota can be requested via the Google Cloud console. The dataset itself updates daily, so caching responses for several hours is the standard pattern.

### How do I pull six months of LCP history through Jentic?

Use the Jentic search query "chrome ux report history record" to discover the records.queryHistoryRecord operation, load its schema, and execute it with the origin or url and metric=largest_contentful_paint. Run pip install jentic to get started.

### Does CrUX cover non-Chrome browsers?

No. The dataset is collected only from opted-in Chrome users on devices that meet the criteria. Use a separate RUM provider if you need data from Safari, Firefox, or Edge users.

### Is the Chrome UX Report API free?

Yes, the API is free within the default project quota. The underlying CrUX dataset is also published as a free public BigQuery dataset for callers who need bulk historical analysis.

### Can I limit what my agent is allowed to do with the Chrome UX Report API?

Yes. Because you run Jentic One yourself, your own rules decide which Chrome UX Report operations the agent may call, so you can allow only queryRecord for current Core Web Vitals, only queryHistoryRecord for six-month trends, or both. Any operation you do not include in that set stays unavailable to the agent unless you add it. Your Google Cloud API key is stored encrypted by your own instance and injected at execution time, so the agent scopes what origins and URLs it queries without ever holding the raw key string.