crux-api

Use when querying Chrome UX Report field data, comparing lab vs field metrics, tracking Core Web Vitals trends, or correlating performance with search rankings. Also use when verifying CWV pass rates or checking p75 thresholds.

Model	Source
sonnet	pack: performance

Full Reference

CrUX API

Chrome UX Report (CrUX) is real user performance data collected from Chrome browsers worldwide. Unlike Lighthouse lab data, CrUX reflects actual user experiences — network conditions, device capabilities, and geographic distribution all factored in. Google uses CrUX field data (not lab data) as the signal for Core Web Vitals ranking.

Quick Reference

Property	Value
Base URL	`https://chromeuxreport.googleapis.com/v1`
Auth	API key via `?key=API_KEY` query param (no OAuth)
Env var	`CRUX_API_KEY`
Rate limit	150 QPM per Google Cloud project (free, cannot be increased)
Data window	28-day rolling average
Update frequency	Daily ~04:00 UTC (queryRecord) / Weekly Monday (History API)
Data lag	~2 days behind current date
Official docs	https://developer.chrome.com/docs/crux/api

Reference Index

I want to…	File
Get an API key, configure env vars, and understand rate limits	`reference/setup.md`
Query site-wide CWV data for an origin or batch multiple origins	`reference/query-origin.md`
Query a specific page URL or compare mobile vs desktop	`reference/query-url.md`
Understand CWV thresholds or parse histogram and p75 values	`reference/metrics.md`
Analyze trends with the History API, detect regressions, or query BigQuery	`reference/historical-data.md`
Handle 404s, rate limit errors, retry with backoff, or set CI gates	`reference/error-handling.md`

Usage: Read the reference file matching your current task from the index above. Each file is self-contained with code examples and inline gotchas.

Announcement

┏━ 📊 crux-api ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Query real-user CWV field data from Chrome UX Report ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛