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.

Start your free trialSee the endpoints

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.

EndpointMCP toolAccess
GET/api/v1/projects/{projectId}/lighthouselist_lighthouse_monitorsRead
POST/api/v1/projects/{projectId}/lighthouseNoneAccount key
GET/api/v1/projects/{projectId}/lighthouse/{monitorId}get_lighthouse_monitorRead
PATCH/api/v1/projects/{projectId}/lighthouse/{monitorId}NoneAccount key
DELETE/api/v1/projects/{projectId}/lighthouse/{monitorId}NoneAccount key
GET/api/v1/projects/{projectId}/lighthouse/{monitorId}/runs/{runId}get_lighthouse_runRead
POST/api/v1/projects/{projectId}/lighthouse/{monitorId}/runstart_lighthouse_runStarts a test
GET/api/v1/projects/{projectId}/lighthouse/budgetsNoneRead
PUT/api/v1/projects/{projectId}/lighthouse/budgetsNoneAccount key

Every monitor of the demo project in one call

GET /api/v1/projects/{projectId}/lighthouse returns each monitor, whether it is within its budget, and the trend of its Lighthouse scores. The answer below is shortened.

Request
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 /api/v1/projects/{projectId}/lighthouse/{monitorId} 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 /api/v1/projects/{projectId}/lighthouse/{monitorId}/run 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 /api/v1/projects/{projectId}/lighthouse/{monitorId}/runs/{runId}: 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/api/mcp 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, stringrequired

    The id of the site. The list of sites gives it.

Example request
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, stringrequired

    The id of the site. The list of sites gives it.

  • urlbody, stringrequired

    The full address of the page, starting with https://.

  • devicebody, string

    mobile or desktop. Default: mobile.

  • schedulebody, string

    hourly 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, stringrequired

    The id of the site. The list of sites gives it.

  • monitorIdpath, stringrequired

    The id of the monitor, from its list.

Example request
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, stringrequired

    The id of the site. The list of sites gives it.

  • monitorIdpath, stringrequired

    The id of the monitor, from its list.

  • schedulebody, stringrequired

    hourly 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, stringrequired

    The id of the site. The list of sites gives it.

  • monitorIdpath, stringrequired

    The 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, stringrequired

    The id of the site. The list of sites gives it.

  • monitorIdpath, stringrequired

    The id of the monitor, from its list.

  • runIdpath, stringrequired

    The id of the run, from the monitor.

Example request
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, stringrequired

    The id of the site. The list of sites gives it.

  • monitorIdpath, stringrequired

    The 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, stringrequired

    The id of the site. The list of sites gives it.

Example request
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, stringrequired

    The id of the site. The list of sites gives it.

  • monitorIdbody, string

    The monitor id. Leave it empty or null for the lines of the site.

  • linesbody, objectrequired

    The 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 /api/v1/projects/{projectId}/lighthouse. 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/api/mcp and reads the runs with the real-user p75 next to them. You install nothing.

Track your first site free.No card needed. Setup takes about 5 minutes.

Start free trialBook a demo