Lighthouse API and MCP with real-user data next to every run
CoreDash runs Lighthouse through PageSpeed Insights on a schedule, so you need no PageSpeed API key and no scheduler of your own.
Every run is kept, the latest 10 with their filmstrip, waterfall and failing audits. Read them over the API, or start a run from your deploy script or your AI.
Lighthouse endpoints, and the key each one needs
Send every call to https://app.coredash.app, followed by the path in the table. A project key or an account key reads monitors and runs, and starts a run. Adding, changing and removing monitors takes an account key, and so does setting their budget lines, your limit per value. The budget routes and the changes to a monitor have no MCP tool: your AI reads and starts runs, and changes nothing.
No cron job
Each monitor is one URL on one device, tested on a schedule you pick from hourly and daily. Until you pick, it runs hourly.
Lab next to field
The p75 of your real users on the same URL and device, over the last 7 days, sits beside the lab values.
Budgets on the median
Set your own limit per value. The score, LCP, FCP and CLS are judged on the median of the last 5 runs, page weight and the bytes on the last 2.
Start after deploys
Start a run from your script or with start_lighthouse_run, up to 20 times per project per UTC day.
| Endpoint | MCP tool | Access |
|---|---|---|
GET/api/ | list_lighthouse_monitors | Read |
POST/api/ | None | Account key |
GET/api/ | get_lighthouse_monitor | Read |
PATCH/api/ | None | Account key |
DELETE/api/ | None | Account key |
GET/api/ | get_lighthouse_run | Read |
POST/api/ | start_lighthouse_run | Starts a test |
GET/api/ | None | Read |
PUT/api/ | None | Account key |
Every monitor of the demo project in one call
GET / returns each monitor, whether it is within its budget, and the trend of its Lighthouse scores. The answer below is shortened.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/lighthouse"AnswerJSON
{
"limit": 20,
"monitors": [
{
"id": "6af829c380055f64eea07dab",
"url": "https://www.corewebvitals.io/",
"device": "mobile",
"schedule": "daily",
"legacy": false,
"lastRunAt": 1794648515238,
"nextRunAt": 1794734915238,
"failures": 0,
"lastError": null,
"runs": [
{
"id": "6af829cd80055f64eea07dac",
"at": 1794648517991,
"values": {
"score": 100,
"LCP": 1280,
"FCP": 936,
"CLS": 0,
"TBT": 0,
"mainThread": 216.3888000000003,
"bootup": 8.8956,
"pageWeight": 220978,
"script": 7000,
"image": 96359,
"css": 0,
"font": 61202,
"thirdParty": 0,
"unusedJs": 0,
"dom": 471,
"requests": 23
},
"lhVersion": "13.6.0",
"full": true
}
],
"lines": [
{"key": "score", "line": 28, "own": false, "state": "few", "value": 100}
],
"trend": [{"at": 1794648517991, "score": 100}]
}
]
}Lighthouse score next to real-user LCP in a client report
Monday morning, your report script calls GET / for the product page on mobile. The answer holds the latest runs and, next to them, the p75 LCP your real users got over the last 7 days. Put the Lighthouse score and the real-user LCP in one row. A green score next to a poor LCP shows the client the gap. Lighthouse loads the page once, on one emulated phone, and their visitors bring their own phones and networks. For where the score is heading, the list of monitors gives the trend of the last 60 runs.
A deploy step that starts a run and reads it back
Once the release is on production, your pipeline calls POST / for the homepage monitor. The call waits for the run and answers when it is done, with the number of starts left today. When the run fails, the answer carries the error from PageSpeed Insights and the start does not count.
A monitor runs at most once per 10 minutes, counted from its last run that worked, scheduled or started. A deploy that lands inside that window gets the answer that the monitor ran less than 10 minutes ago. That run may be older than your release, so start again once the window has passed.
After the answer, the new run is the newest one on the monitor. Read it in full with GET /: the score, lab LCP, total blocking time, page weight and the failing audits.
Want the build to fail on a heavy bundle? Check the bytes of JavaScript in that run against your own line. Bytes barely move from one run to the next. The score moves a few points every run, so a build that fails on one score fails at random. Leave the score to the budget in CoreDash, which judges it on the median of the last 5 runs.
Lighthouse MCP: ask your AI to test the checkout page
"Run Lighthouse on the checkout page and compare it with real users." Connect CoreDash as an MCP server at https://app.coredash.app/ and your AI gets 4 Lighthouse tools. It finds the monitor you added for the checkout page on mobile, calls start_lighthouse_run on it and waits for the run. Then get_lighthouse_monitor puts the new run next to the p75 of your visitors on checkout, and get_lighthouse_run adds its failing audits. Your AI comes back with lab LCP next to real-user LCP, and the audits to look at. There is nothing to install and no Chrome on your laptop: the test happens in PageSpeed Insights, and the run stays in the monitor.
Lighthouse API reference
Every endpoint and MCP tool for Lighthouse, with its parameters and a real answer.
GET/api/v1/projects/{projectId}/lighthouse
Lighthouse monitors: a page and device tested on a schedule through PageSpeed Insights, with the state of their budget lines and the scores of their last runs. All values are lab values.
MCP tool: list_lighthouse_monitors
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/lighthouse"AnswerJSON
{
"limit": 20,
"monitors": [
{
"id": "6af829c380055f64eea07dab",
"url": "https://www.corewebvitals.io/",
"device": "mobile",
"schedule": "daily",
"legacy": false,
"lastRunAt": 1794648515238,
"nextRunAt": 1794734915238,
"failures": 0,
"lastError": null,
"runs": [
{
"id": "6af829cd80055f64eea07dac",
"at": 1794648517991,
"values": {
"score": 100,
"LCP": 1280,
"FCP": 936,
"CLS": 0,
"TBT": 0,
"mainThread": 216.3888000000003,
"bootup": 8.8956,
"pageWeight": 220978,
"script": 7000,
"image": 96359,
"css": 0,
"font": 61202,
"thirdParty": 0,
"unusedJs": 0,
"dom": 471,
"requests": 23
},
"lhVersion": "13.6.0",
"full": true
}
],
"lines": [
{"key": "score", "line": 28, "own": false, "state": "few", "value": 100}
],
"trend": [{"at": 1794648517991, "score": 100}]
}
]
}POST/api/v1/projects/{projectId}/lighthouse
Adds a Lighthouse monitor. The first run is due at once.
Use an account key for this call.
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
urlbody, stringrequiredThe full address of the page, starting with https://.
devicebody, stringmobile or desktop. Default: mobile.
schedulebody, stringhourly or daily. Default: hourly.
GET/api/v1/projects/{projectId}/lighthouse/{monitorId}
One Lighthouse monitor with its runs, its budget lines and the p75 of real users on the same page and device.
MCP tool: get_lighthouse_monitor
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
monitorIdpath, stringrequiredThe id of the monitor, from its list.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/lighthouse/6af829c380055f64eea07dab"AnswerJSON
{
"monitor": {
"id": "6af829c380055f64eea07dab",
"url": "https://www.corewebvitals.io/",
"device": "mobile",
"schedule": "daily",
"legacy": false,
"lastRunAt": 1794648515238,
"nextRunAt": 1794734915238,
"failures": 0,
"lastError": null,
"runs": [
{
"id": "6af829cd80055f64eea07dac",
"at": 1794648517991,
"values": {
"score": 100,
"LCP": 1280,
"FCP": 936,
"CLS": 0,
"TBT": 0,
"mainThread": 216.3888000000003,
"bootup": 8.8956,
"pageWeight": 220978,
"script": 7000,
"image": 96359,
"css": 0,
"font": 61202,
"thirdParty": 0,
"unusedJs": 0,
"dom": 471,
"requests": 23
},
"lhVersion": "13.6.0",
"full": true
}
]
},
"lines": [
{"key": "score", "line": 28, "own": false, "state": "few", "value": 100}
],
"budgets": [
{
"id": "l_project",
"monitorId": null,
"lines": {
"pageWeight": 2746804,
"image": 676276,
"css": 32873,
"font": 79573,
"thirdParty": 1335698,
"dom": 3335,
"script": 1816110,
"unusedJs": 1225315,
"score": 28
},
"legacy": true
}
],
"rum": {
"range": {"start": 1794149437717, "end": 1794754237717},
"windows": {
"cur": [1794149437717, 1794754237717],
"prev": [1793544637717, 1794149437717],
"length": 604800000,
"adapted": false
},
"metrics": {
"LCP": {
"count": 24,
"p": {"p50": 408, "p75": 708, "p80": 832, "p90": 832, "p95": 1300},
"shares": [0.9583333333333334, 0.04166666666666663, 0],
"prev": {
"count": 22,
"p": {"p50": 400, "p75": 2788, "p80": 2788, "p90": 2788, "p95": 2788},
"lowSample": true
},
"lowSample": true
},
"INP": {
"count": 15,
"p": {"p50": 38, "p75": 65, "p80": 65, "p90": 147, "p95": 171},
"shares": [1, 0, 0],
"prev": {
"count": 14,
"p": {"p50": 62, "p75": 128, "p80": 130, "p90": 132, "p95": 132},
"lowSample": true
},
"lowSample": true
},
"CLS": {
"count": 24,
"p": {"p50": 0, "p75": 0, "p80": 0, "p90": 0, "p95": 0},
"shares": [1, 0, 0],
"prev": {
"count": 20,
"p": {"p50": 0, "p75": 0, "p80": 0, "p90": 0, "p95": 0},
"lowSample": true
},
"lowSample": true
},
"FCP": {
"count": 24,
"p": {"p50": 264, "p75": 476, "p80": 528, "p90": 632, "p95": 1168},
"shares": [0.9583333333333334, 0.04166666666666663, 0],
"prev": {
"count": 22,
"p": {"p50": 180, "p75": 500, "p80": 552, "p90": 1048, "p95": 2320},
"lowSample": true
},
"lowSample": true
},
"TTFB": {
"count": 24,
"p": {"p50": 100, "p75": 313, "p80": 354, "p90": 354, "p95": 657},
"shares": [0.9583333333333334, 0, 0.04166666666666663],
"prev": {
"count": 22,
"p": {"p50": 202, "p75": 2495, "p80": 2495, "p90": 2495, "p95": 2495},
"lowSample": true
},
"lowSample": true
}
}
}
}PATCH/api/v1/projects/{projectId}/lighthouse/{monitorId}
Changes how often a monitor runs.
Use an account key for this call.
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
monitorIdpath, stringrequiredThe id of the monitor, from its list.
schedulebody, stringrequiredhourly or daily.
DELETE/api/v1/projects/{projectId}/lighthouse/{monitorId}
Deletes a monitor with its runs and its own budget lines.
Use an account key for this call.
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
monitorIdpath, stringrequiredThe id of the monitor, from its list.
GET/api/v1/projects/{projectId}/lighthouse/{monitorId}/runs/{runId}
One Lighthouse run: its values and, while the run is kept in full, the filmstrip, the waterfall and the failing audits.
MCP tool: get_lighthouse_run
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
monitorIdpath, stringrequiredThe id of the monitor, from its list.
runIdpath, stringrequiredThe id of the run, from the monitor.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/lighthouse/6af829c380055f64eea07dab/runs/6af829cd80055f64eea07dac"AnswerJSON
{
"monitor": {
"id": "6af829c380055f64eea07dab",
"url": "https://www.corewebvitals.io/",
"device": "mobile",
"schedule": "daily",
"legacy": false,
"lastRunAt": 1794648515238,
"nextRunAt": 1794734915238,
"failures": 0,
"lastError": null,
"runs": [
{
"id": "6af829cd80055f64eea07dac",
"at": 1794648517991,
"values": {
"score": 100,
"LCP": 1280,
"FCP": 936,
"CLS": 0,
"TBT": 0,
"mainThread": 216.3888000000003,
"bootup": 8.8956,
"pageWeight": 220978,
"script": 7000,
"image": 96359,
"css": 0,
"font": 61202,
"thirdParty": 0,
"unusedJs": 0,
"dom": 471,
"requests": 23
},
"lhVersion": "13.6.0",
"full": true
}
]
},
"run": {
"id": "6af829cd80055f64eea07dac",
"at": 1794648517991,
"values": {
"score": 100,
"LCP": 1280,
"FCP": 936,
"CLS": 0,
"TBT": 0,
"mainThread": 216.3888000000003,
"bootup": 8.8956,
"pageWeight": 220978,
"script": 7000,
"image": 96359,
"css": 0,
"font": 61202,
"thirdParty": 0,
"unusedJs": 0,
"dom": 471,
"requests": 23
},
"lhVersion": "13.6.0",
"full": true,
"fullData": {
"filmstrip": [{"ms": 375, "data": "data:image/jpeg;base64,…"}],
"finalScreenshot": "data:image/jpeg;base64,…",
"requests": [
{
"url": "https://www.corewebvitals.io/",
"type": "Document",
"start": 2.0100000202655792,
"end": 54.05500000715256,
"size": 17308,
"priority": "VeryHigh",
"preload": false,
"status": 200
}
],
"lcp": {
"selector": "article.article > div#text > section.herop > img.hphi",
"snippet": "<img class=\"hphi\" src=\"/static/img/resize-800-1200/s/arjen-rsd.webp\" alt=\"Arjen Karel, Core Web Vitals consultant\" width=\"800\" height=\"1200\" fetchpriority=\"high…",
"label": "Arjen Karel, Core Web Vitals consultant",
"ttfb": 2.258,
"loadDelay": 60.556,
"loadDuration": 53.479,
"renderDelay": 73.856
},
"milestones": {"TTFB": 601, "FCP": 936, "LCP": 1280, "DCL": 173, "Load": 178},
"audits": [
{
"id": "lcp-discovery-insight",
"title": "LCP request discovery",
"display": null,
"score": 0,
"group": "LCP",
"savingsMs": null,
"savingsBytes": null
}
]
}
}
}POST/api/v1/projects/{projectId}/lighthouse/{monitorId}/run
Runs a Lighthouse monitor now and answers when the run is done, with the starts left today in left. A failed run answers with the error from PageSpeed Insights and does not count. One monitor runs at most once per 10 minutes, scheduled runs included.
MCP tool: start_lighthouse_run
Starts per site per day: 20.
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
monitorIdpath, stringrequiredThe id of the monitor, from its list.
GET/api/v1/projects/{projectId}/lighthouse/budgets
Lists the Lighthouse budget lines of the site and of each monitor.
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/lighthouse/budgets"AnswerJSON
{
"budgets": [
{
"id": "l_project",
"monitorId": null,
"lines": {
"pageWeight": 2746804,
"image": 676276,
"css": 32873,
"font": 79573,
"thirdParty": 1335698,
"dom": 3335,
"script": 1816110,
"unusedJs": 1225315,
"score": 28
},
"legacy": true
}
]
}PUT/api/v1/projects/{projectId}/lighthouse/budgets
Sets the budget lines of the site, or of one monitor. Empty lines remove them.
Use an account key for this call.
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
monitorIdbody, stringThe monitor id. Leave it empty or null for the lines of the site.
linesbody, objectrequiredThe limit per value, keyed by score, LCP, FCP, CLS, pageWeight, script, image, css, font, thirdParty, unusedJs and dom.
One account key for the whole agency
An account key reads the Lighthouse monitors of every project in your account, so one report script covers all your clients. The same key adds monitors and sets their budget lines. See the agency API and agency pricing.
Get a key, then connect your AI or your pipeline
Frequently asked questions
Do I need a PageSpeed Insights API key?
No. CoreDash calls the Google PageSpeed API for you, on each monitor's schedule. If you searched for a Google Lighthouse API, PageSpeed Insights is it. You only need a CoreDash key: a project key for one site, or an account key for every project. MCP clients can also sign in with OAuth.
Does the Lighthouse API cost extra?
No. The API and the MCP server come with every paid plan and every running trial, and the Lighthouse runs are part of it. A key makes 60 calls per minute by default, up to 960 on the largest plans.
How often does CoreDash run Lighthouse?
Every monitor runs hourly until you pick another schedule; the choices are hourly and daily. Each device (mobile and desktop) is its own monitor, and each project gets 20 monitors. A start from your script or your AI runs at once and takes the place of the next scheduled run, which then follows one interval later. You get 20 starts per project per UTC day, with at most one run per monitor every 10 minutes, scheduled runs included.
Is the score the same as PageSpeed Insights?
Yes. It is the run PageSpeed Insights does, with the same colours: good from 90, poor under 50. Run it twice and the score moves a few points, which is why a budget judges the score on the median of the last 5 runs.
Why does Lighthouse disagree with my real users?
Because Lighthouse loads the page once, on one emulated device with a throttled connection and an empty cache. The real-user p75 comes from your visitors over the last 7 days. A PageSpeed Insights run also has no INP, since nobody clicks during a page load. Total blocking time is the closest lab value, and CoreDash shows it as a trend without a budget.
What does a Lighthouse run measure?
Every run records the score, the lab timings, the bytes per kind of file and the size of the page. In full: Performance score, Largest Contentful Paint, First Contentful Paint, Cumulative Layout Shift, Total Blocking Time, Main thread work, JavaScript execution time, Page weight, JavaScript, Images, CSS, Fonts, Third-party, Unused JavaScript, DOM elements and Requests. The last 10 runs also keep the filmstrip, the requests and the audits.
Can I add monitors through the API?
Yes, with an account key. Send a URL, a device and a schedule to POST /. The same key changes the schedule, removes a monitor and sets its budget lines; the calls are in the table above. A project key reads monitors and starts runs.
Does the Lighthouse MCP server run Lighthouse on my machine?
No. CoreDash runs it through PageSpeed Insights and keeps the run in the monitor. Your AI connects to https://app.coredash.app/ and reads the runs with the real-user p75 next to them. You install nothing.