CrUX API and MCP with your real users next to Google's numbers
CoreDash calls Google's Chrome UX Report API for you, without a Google key, and shows your real-user data beside your site's CrUX.
CrUX is the field data Google collects from Chrome users, per origin or URL, over a rolling 28-day window. With your site's CrUX record you get the p75 and page views of your own Chrome visitors over the same days, and the day CoreDash expects each Core Web Vital to pass. Your script reads it with a CoreDash key, and your AI reads it over MCP.
CrUX endpoints and their MCP tools
Every path in the table starts at https://app.coredash.app. A project key or an account key reads your site's CrUX record and its list of competitors and pages. Adding or removing a competitor or a page takes an account key. Those two calls have no MCP tool, so your AI reads the list but never changes it.
No Google key
CoreDash asks Google with its own key and keeps each answer 24 hours. Google updates CrUX once a day.
Your Chrome visitors
Their p75 and page views in CoreDash, over exactly the days the CrUX record covers.
Expected pass date
Per vital, the day your origin's 28-day CrUX window should turn Good. Search Console reports on the same days, per group of pages.
Competitors and pages
Up to 10 competitor origins and 20 of your own URLs, each with its CrUX record. Your site and its competitors also come with their weekly CrUX history.
| Endpoint | MCP tool | Access |
|---|---|---|
GET/api/ | get_crux | Read |
GET/api/ | get_crux_targets | Read |
POST/api/ | None | Account key |
DELETE/api/ | None | Account key |
The demo site's CrUX and its own visitors, in one call
This is GET / on the demo project, as it answered. Per vital you get the CrUX p75 and Good share, the demo site's own Chrome numbers for the same days, and the forecast of the day that vital passes. On the demo site every vital passes already. Add d=mobile or d=desktop for one device. Leave it out and CrUX counts all devices together.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/crux"AnswerJSON
{
"origin": "https://www.corewebvitals.io",
"record": {
"found": true,
"first": 1792195200000,
"last": 1794528000000,
"metrics": {
"LCP": {"p75": 715, "good": 0.9789},
"INP": {"p75": 44, "good": 0.9825},
"CLS": {"p75": 0, "good": 0.994}
}
},
"rum": {
"LCP": {"p75": 920, "views": 2510},
"INP": {"p75": 43, "views": 1212},
"CLS": {"p75": 0, "views": 2573}
},
"forecasts": {
"LCP": {"state": "passes"},
"INP": {"state": "passes"},
"CLS": {"state": "passes"}
}
}A monthly client report with the day each vital passes
At the start of each month your report script calls GET / with d=mobile for every client site. For LCP, INP and CLS it writes one row each: the CrUX p75, Google's number for the whole site, and beside it what the client's Chrome visitors measured in CoreDash over the same days.
When the forecast comes back as date, the row gets the day that vital should pass. Print that date as it is. The days in the same forecast count from the last day of the CrUX record, which is about two days behind today, so "passes in so many days" would come out too long.
Your competitors' CrUX LCP, checked every Tuesday
Google adds a new week to the CrUX history every Monday, and CoreDash keeps each answer 24 hours, so a call on Monday can still bring back last week. Run your script on Tuesday afternoon, UTC, and call GET /. To be sure the new week is in, check that the last date in ends is last Saturday: Google's Monday update holds the data up to the Saturday before.
The answer starts with your own site (id: "own"), then each competitor with its CrUX record and weekly history. A history lists ends, the last day of each period, oldest first, and per vital a p75 and a good array in the same order. For the week's move, compare a competitor's last LCP p75 with the last earlier week that has one. A week without enough Chrome traffic comes back as null.
Every period is a full 28-day window. A competitor that relaunches with a faster LCP improves a little each week, until its old days have left the window.
When will Search Console show my LCP as good?
Ask your AI exactly that. Connect CoreDash as an MCP server at https://app.coredash.app/ and it gets 2 CrUX tools. For your site on mobile it calls get_crux and reads the LCP forecast: passes when the window is Good already, or date with the day it should turn Good. Your AI answers with that day and sets the CrUX p75 against the p75 of your Chrome visitors.
That date is for your whole origin. Search Console's Core Web Vitals report judges groups of pages, so a slow template can stay red for a while after the origin passes.
If the forecast says needs-rum, your last 7 days in CoreDash are not fast enough to pull the window to Good, and CoreDash gives no date until your real users get faster. The tool tells your AI to say CrUX whenever it quotes a CrUX number, so Google's numbers stay apart from your own field data. Ask how a competitor is doing and it calls get_crux_targets.
CrUX API reference
Every CrUX endpoint with its MCP tool and parameters, and a real answer for each read.
GET/api/v1/projects/{projectId}/crux
Google's CrUX record for the origin of the site (Chrome users only), with CoreDash's own field data from Chrome for the same days next to it. Per Core Web Vital it gives the day the CrUX window is expected to turn Good.
MCP tool: get_crux
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
dquery, stringDefault: all.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/crux"AnswerJSON
{
"origin": "https://www.corewebvitals.io",
"record": {
"found": true,
"first": 1792195200000,
"last": 1794528000000,
"metrics": {
"LCP": {"p75": 715, "good": 0.9789},
"INP": {"p75": 44, "good": 0.9825},
"CLS": {"p75": 0, "good": 0.994}
}
},
"rum": {
"LCP": {"p75": 920, "views": 2510},
"INP": {"p75": 43, "views": 1212},
"CLS": {"p75": 0, "views": 2573}
},
"forecasts": {
"LCP": {"state": "passes"},
"INP": {"state": "passes"},
"CLS": {"state": "passes"}
}
}GET/api/v1/projects/{projectId}/crux/targets
CrUX data for the competitors and own pages added on the CrUX page, with the site itself first.
MCP tool: get_crux_targets
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
dquery, stringDefault: all.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/crux/targets"AnswerJSON
{
"competitors": {
"sites": [
{
"id": "own",
"name": "www.corewebvitals.io",
"origin": "https://www.corewebvitals.io",
"legacy": false,
"own": true
}
],
"records": [
{
"found": true,
"first": 1792195200000,
"last": 1794528000000,
"metrics": {
"LCP": {"p75": 715, "good": 0.9789},
"INP": {"p75": 44, "good": 0.9825},
"CLS": {"p75": 0, "good": 0.994}
}
}
],
"histories": [
{
"found": true,
"ends": [
1779494400000,
1780099200000,
1780704000000,
1781308800000,
1781913600000,
1782518400000,
1783123200000,
1783728000000,
1784332800000,
1784937600000,
1785542400000,
1786147200000,
1786752000000,
1787356800000,
1787961600000,
1788566400000,
1789171200000,
1789776000000,
1790380800000,
1790985600000,
1791590400000,
1792195200000,
1792800000000,
1793404800000,
1794009600000
],
"metrics": {
"LCP": {
"p75": [
631,
null,
638,
632,
667,
688,
737,
738,
null,
null,
663,
null,
604,
579,
638,
679,
null,
null,
713,
673,
620,
null,
665,
706,
744
],
"good": [
0.9854,
null,
0.9901,
0.9895,
0.9856,
0.9848,
0.9798,
0.982,
null,
null,
0.9839,
null,
0.9874,
0.9929,
0.9896,
0.986,
null,
null,
0.9814,
0.9794,
0.9923,
null,
0.9825,
0.9781,
0.9737
]
},
"INP": {
"p75": [
57,
56,
56,
49,
49,
47,
48,
45,
47,
48,
46,
49,
48,
48,
53,
52,
56,
57,
47,
47,
45,
42,
39,
37,
43
],
"good": [
0.9742,
0.9751,
0.9832,
0.9832,
0.9798,
0.9802,
0.9786,
0.9742,
0.986,
0.9866,
0.9835,
0.9856,
0.9851,
0.9829,
0.989,
0.9924,
0.9875,
0.9838,
0.9861,
0.9703,
0.9813,
0.9855,
0.9782,
0.9816,
0.9826
]
},
"CLS": {
"p75": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
null,
0,
0,
0,
0,
0,
0,
0
],
"good": [
0.9934,
0.9906,
0.9903,
0.9955,
0.9936,
0.9905,
0.9916,
0.99,
0.9889,
0.9879,
0.9877,
0.9914,
0.9939,
0.998,
0.9977,
1,
0.9973,
null,
0.9972,
0.996,
0.9974,
0.9977,
0.9956,
0.9952,
0.9954
]
}
}
}
],
"hidden": 17
},
"pages": {
"pages": [
{
"id": "l_695bb89ad5b0893414b1d305",
"kind": "page",
"value": "https://www.corewebvitals.io",
"legacy": true
}
],
"records": [{"found": false, "reason": "Not enough Chrome traffic in CrUX"}]
}
}POST/api/v1/projects/{projectId}/crux/targets
Adds a competitor, or one of your own pages, to follow in CrUX.
Use an account key for this call.
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
kindbody, stringrequiredcompetitor or page.
valuebody, stringrequiredA host such as www.example.com for a competitor, a full address for a page.
DELETE/api/v1/projects/{projectId}/crux/targets/{targetId}
Removes a competitor or a page.
Use an account key for this call.
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
targetIdpath, stringrequiredThe id of the competitor or page, from the CrUX targets.
One account key for every client site
An account key reads the CrUX record of every project in your account, so one script builds every client's report. The same key adds and removes each client's competitors and pages. See the agency API and agency pricing.
Related pages
Frequently asked questions
Do I need a CrUX API key?
No. CoreDash calls Google's CrUX API with its own key, on its server. You only need a CoreDash key: a project key for one site, or an account key for every project. To call Google yourself, you need a Google Cloud API key provisioned for the Chrome UX Report API. Google's CrUX API docs explain how to get one.
How fresh is the CrUX data?
About two days old, plus the time CoreDash has kept the answer. Google waits for complete days, so the last day in CrUX is about two days before today. CoreDash keeps each answer up to 24 hours before it asks Google again. The record names its first and last day, so your script can see how old it is. The history gets one new period a week, on Mondays.
Why does CrUX differ from my CoreDash numbers?
Because they count different visitors. CrUX holds only Chrome users on desktop and Android who share usage statistics and sync their browsing history. Chrome on iOS is left out. CoreDash counts every page view on a page with its script. The CoreDash numbers beside CrUX use only Chrome page views, from the record's first to its last day, so most of what stays different is the visitors CrUX never sees.
How does CoreDash work out the day a vital turns Good?
It moves the 28-day window forward one day at a time and looks for the first day its p75 is Good, with each new day expected to look like the last 7 days of your CoreDash data. The gap between CrUX and CoreDash over the current window corrects for the visitors each one counts. The answer gives that day as date, and in days how far it falls after the record's last day. Below 200 CoreDash page views in the window there is no forecast: you get unknown with few-views.
What if my site is not in CrUX?
Then the record says found: false, with a reason: the origin or URL has too little Chrome traffic for a CrUX record. The forecast says unknown with no-crux. That answer is cached like any other. A network error is not, so the next call asks Google again. Your CoreDash field data does not depend on CrUX and keeps coming in. See not enough data in Core Web Vitals.
How much CrUX history do I get?
25 weekly periods, for your site and every competitor in the answer. CoreDash asks Google's CrUX History API for them when you call GET /. The periods come oldest first, each a 28-day window ending on its date in ends. Your own pages get their current CrUX record, without history. Google's History API docs explain how the periods are built.
Can I add competitors through the API?
Yes, with an account key. Send kind: competitor with a host such as www.example.com in value, or kind: page with a full URL, to POST /. Remove one with DELETE /. A site takes up to 10 competitors and 20 pages, and it is never its own competitor. Competitors carried over from the earlier CoreDash app can go past that limit. The answer then shows 10 of them, and hidden counts the rest.
Is the CrUX API free?
Google's is, within a quota per Google Cloud project. In CoreDash the CrUX endpoints cost nothing extra: they are part of the API, which every paid plan and every running trial includes. A key gets 60 to 960 calls a minute, and the CoreDash API lists the limit per plan.