RUM API for real-user Core Web Vitals per page and device, as JSON
Real visitors' LCP, INP and CLS, split by country, browser, LCP element or any of 40 dimensions, ready for your own dashboard or client report.
RUM endpoints and their MCP tools
The numbers come from the CoreDash tracker on your site. Install it, one snippet in the head of your pages, and everything it measures is in the API.
Every number in the app
8 endpoints. The CoreDash app draws its own charts and tables from them.
Any dimension
Filter and split every query on the same keys: page, device, INP element, the script in a long animation frame. list_dimensions lists the rest.
Percentile and period
p50, p75, p80, p90 and p95 (default p75), over a preset or your own dates in the last 56 days.
The same reads for your AI
9 MCP tools take the same arguments as the endpoints, so your AI quotes the numbers you see on screen.
| Endpoint | MCP tool | What you get |
|---|---|---|
GET/api/ | list_dimensions | Every dimension, its known values and the metrics it applies to |
GET/api/ | get_summary | Core Web Vitals for a period, with percentiles and Good, Needs improvement and Poor shares |
GET/api/ | get_breakdown | Metrics split by a dimension: one row per page, country or LCP element |
GET/api/ | get_timeseriesget_segment_timeseries | Metrics over time, with a trend: improving, stable or regressing |
GET/api/ | get_histogram | Pageviews per bucket of one metric |
GET/api/ | get_phases | The sub-phases of LCP, INP or TTFB |
GET/api/ | get_values | The values a dimension has, most pageviews first |
GET/api/ | list_views | The Explore views of the site, with their pins |
Send each call to https://app.coredash.app plus the path in the table, with your key in Authorization: Bearer cdk_your_key. Your key reads every site you can open in CoreDash; you make it under Account > API keys. GET /api/v1/projects gives the projectId of each site.
The demo project's Core Web Vitals in one call
GET /api/v1/projects/{projectId}/summary returns, per metric, the pageviews in count, the percentiles in p and, in shares, the fractions rated Good, Needs improvement and Poor, in that order. The answer below is real, from the CoreDash demo project.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/summary?date=-7d"AnswerJSON
{
"range": {"start": 1794149435575, "end": 1794754235575},
"windows": null,
"metrics": {
"LCP": {
"count": 703,
"p": {"p50": 452, "p75": 756, "p80": 892, "p90": 1526, "p95": 2220},
"shares": [0.9615931721194879, 0.02987197724039825, 0.008534850640113834],
"prev": null
},
"INP": {
"count": 367,
"p": {"p50": 14, "p75": 39, "p80": 44, "p90": 67, "p95": 107},
"shares": [0.9863760217983651, 0.008174386920980936, 0.00544959128065392],
"prev": null
},
"CLS": {
"count": 655,
"p": {"p50": 0, "p75": 0, "p80": 0, "p90": 0.021, "p95": 1},
"shares": [0.9297709923664123, 0.007633587786259555, 0.0625954198473282],
"prev": null
},
"FCP": {
"count": 717,
"p": {"p50": 376, "p75": 652, "p80": 760, "p90": 1256, "p95": 1936},
"shares": [0.9414225941422594, 0.04323570432357049, 0.015341701534170138],
"prev": null
},
"TTFB": {
"count": 753,
"p": {"p50": 137, "p75": 354, "p80": 414, "p90": 827, "p95": 1485},
"shares": [0.8950863213811421, 0.06905710491367867, 0.03585657370517925],
"prev": null
}
}
}Mobile LCP per template in Monday's report
Your report script calls GET /api/v1/projects/{projectId}/breakdown with metrics=LCP, dimension=lb and d=mobile. lb is the page label your site sends with each pageview, such as product or blog (how to set one), and every label comes back as its own row. Add compare=1 and each row also holds the period before in prev, so the client sees whether the product pages got faster or slower. A site without labels gets one empty row; send dimension=ff there and report per folder.
A value resting on fewer than 50 pageviews carries lowSample. Keep it out of the red column: a few slow visits on a quiet template tell the client nothing yet.
An INP chart on your team's own dashboard
Your dashboard calls GET /api/v1/projects/{projectId}/series with metrics=INP, d=mobile, date=-7d and granularity=day, and draws a point per day. Next to the points, the answer holds a trend: improving, stable or regressing. CoreDash compares the second half of the period with the first, by the noise rule the app uses, so a small wobble stays stable. Keep the period short for this: over the default -28d, this week's slip shares the second half with the week before it, so the trend is slow to say regressing.
For a line per template, send metric=INP, dimension=lb and one values per label, as in values=product&values=blog. Each line comes with its own trend. A sudden jump usually lines up with a deploy; a slow slide is more often third-party scripts piling up. Your AI reads the same lines with get_segment_timeseries.
Ask your AI which button makes product pages slow to respond
Connect CoreDash as an MCP server at https://app.coredash.app/api/mcp and ask. Your AI calls get_breakdown for INP with dimension=inpel, filtered to product pages on mobile, and gets the elements visitors interacted with, each with its pageviews and percentiles. The same call with lurl names the scripts that ran in the long animation frames behind those interactions.
RUM API reference
Every RUM endpoint and MCP tool, with its parameters and a real answer. Filters like d=mobile work on summary, breakdown, series, histogram, phases and values.
What one request can ask for
- Breakdown rows: 50 by default, at most 500.
- Histogram buckets: 40 by default, from 5 to 80.
- Segment series: at most 20 values.
GET/api/v1/dimensions
Every dimension: key, label, category, unit, known values and codes, and the metrics it applies to. Also the filter operators. Use the keys in filters and as dimension.
MCP tool: list_dimensions
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/dimensions"AnswerJSON
{
"dimensions": [
{
"key": "ab",
"label": "A/B test",
"category": "Experiment",
"unit": null,
"values": null,
"codes": null,
"metrics": ["LCP", "INP", "CLS", "FCP", "TTFB"]
}
],
"operators": [{"prefix": "", "label": "is"}],
"note": "Several values separated by a new line match any of them. With [wild], * matches any text."
}GET/api/v1/projects/{projectId}/summary
Core Web Vitals for a period. Per metric: page views (count), p50 to p95 (p) and the share of page views rated Good, Needs improvement and Poor (shares, in that order). Use it for questions like "what is my LCP on mobile?".
MCP tool: get_summary
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
metricsquery, stringMetrics, separated by commas. Default: LCP,INP,CLS,FCP,TTFB.
datequery, stringPeriod. Default: -28d.
startdatequery, stringFirst day (YYYY-MM-DD, UTC), with enddate.
enddatequery, stringLast day, included.
comparequery, 1 or 0Also read the period before into prev.
any dimension keyquery, stringLimits the page views to a value of that dimension, for example d=mobile. GET /api/v1/dimensions lists the keys.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/summary?date=-7d"AnswerJSON
{
"range": {"start": 1794149435575, "end": 1794754235575},
"windows": null,
"metrics": {
"LCP": {
"count": 703,
"p": {"p50": 452, "p75": 756, "p80": 892, "p90": 1526, "p95": 2220},
"shares": [0.9615931721194879, 0.02987197724039825, 0.008534850640113834],
"prev": null
},
"INP": {
"count": 367,
"p": {"p50": 14, "p75": 39, "p80": 44, "p90": 67, "p95": 107},
"shares": [0.9863760217983651, 0.008174386920980936, 0.00544959128065392],
"prev": null
},
"CLS": {
"count": 655,
"p": {"p50": 0, "p75": 0, "p80": 0, "p90": 0.021, "p95": 1},
"shares": [0.9297709923664123, 0.007633587786259555, 0.0625954198473282],
"prev": null
},
"FCP": {
"count": 717,
"p": {"p50": 376, "p75": 652, "p80": 760, "p90": 1256, "p95": 1936},
"shares": [0.9414225941422594, 0.04323570432357049, 0.015341701534170138],
"prev": null
},
"TTFB": {
"count": 753,
"p": {"p50": 137, "p75": 354, "p80": 414, "p90": 827, "p95": 1485},
"shares": [0.8950863213811421, 0.06905710491367867, 0.03585657370517925],
"prev": null
}
}
}GET/api/v1/projects/{projectId}/breakdown
Metrics split by a dimension: one row per value (a page, a country, an LCP element) with its page views and percentiles. Use it to find the pages, devices or elements behind a slow metric. Attribution dimensions such as lcpel, inpel and clsel name the element; lurl names the scripts in long animation frames behind INP.
MCP tool: get_breakdown
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
metricsquery, stringOne metric, or several separated by commas. Default: LCP,INP,CLS,FCP,TTFB.
dimensionquery, stringrequiredSplit by this dimension. A key from filters.
limitquery, integerMost rows. Default: 50, at most 500.
datequery, stringPeriod. Default: -28d.
startdatequery, stringFirst day (YYYY-MM-DD, UTC), with enddate.
enddatequery, stringLast day, included.
comparequery, 1 or 0Also read the period before into prev.
any dimension keyquery, stringLimits the page views to a value of that dimension, for example d=mobile. GET /api/v1/dimensions lists the keys.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/breakdown?date=-7d&dimension=ff"AnswerJSON
{
"range": {"start": 1794149435717, "end": 1794754235717},
"dimension": "ff",
"windows": null,
"rows": [
{
"key": "pagespeed",
"stats": {
"LCP": {
"count": 134,
"p": {"p50": 500, "p75": 704, "p80": 768, "p90": 1056, "p95": 1576},
"shares": [0.9850746268656716, 0.007462686567164201, 0.007462686567164201],
"prev": null
},
"INP": {
"count": 62,
"p": {"p50": 8, "p75": 37, "p80": 42, "p90": 85, "p95": 107},
"shares": [1, 0, 0],
"prev": null
},
"CLS": {
"count": 123,
"p": {"p50": 0, "p75": 0, "p80": 0, "p90": 0, "p95": 0.008},
"shares": [1, 0, 0],
"prev": null
},
"FCP": {
"count": 136,
"p": {"p50": 452, "p75": 597, "p80": 644, "p90": 960, "p95": 1088},
"shares": [0.9852941176470589, 0.007352941176470562, 0.007352941176470562],
"prev": null
},
"TTFB": {
"count": 140,
"p": {"p50": 119, "p75": 243, "p80": 264, "p90": 490, "p95": 549},
"shares": [0.9642857142857143, 0.021428571428571463, 0.014285714285714235],
"prev": null
}
}
}
]
}GET/api/v1/projects/{projectId}/series
Metrics over time: per metric a list of points with value and page views, and a trend that compares the second half of the period with the first (improving, stable or regressing, by the same noise rule as the app's comparison; null with too few page views). Use it for "did it get worse?" and to check a release.
One metric over time with a line per value of a dimension (two pages, three countries), each with its points and trend. Get the values from get_values or get_breakdown.
MCP tool: get_timeseries, get_segment_timeseries
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
metricsquery, stringMetrics, separated by commas. Default: LCP,INP,CLS,FCP,TTFB.
datequery, stringPeriod. Default: -28d.
startdatequery, stringFirst day (YYYY-MM-DD, UTC), with enddate.
enddatequery, stringLast day, included.
granularityquery, stringSize of one point. Default: the size the app's chart uses for the period.
percentilequery, stringPercentile of each point. Default: p75.
comparequery, 1 or 0Also read the period before into prev.
any dimension keyquery, stringLimits the page views to a value of that dimension, for example d=mobile. GET /api/v1/dimensions lists the keys.
metricquery, stringOne metric. Default: LCP.
dimensionquery, stringThe dimension the values belong to. A key from filters.
valuesquery, stringThe values to chart, separated by a new line, at most 20. [empty] is the line for page views without a value.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/series?date=-7d"AnswerJSON
{
"start": 1794149435822,
"end": 1794754235822,
"bucketMs": 86400000,
"windows": null,
"points": {
"LCP": [{"t": 1794096000000, "value": 1044, "count": 13, "lowSample": true}],
"INP": [{"t": 1794096000000, "value": 17, "count": 4, "lowSample": true}],
"CLS": [{"t": 1794096000000, "value": 0, "count": 8, "lowSample": true}],
"FCP": [{"t": 1794096000000, "value": 1280, "count": 13, "lowSample": true}],
"TTFB": [{"t": 1794096000000, "value": 729, "count": 13, "lowSample": true}]
},
"trend": {
"LCP": {
"recent": 821.75,
"previous": 713.3333333333334,
"change": 15.2,
"trend": "regressing"
},
"INP": {"recent": 39.25, "previous": 37, "change": 6.1, "trend": "stable"},
"CLS": {"recent": 0.00725, "previous": 0, "change": null, "trend": "stable"},
"FCP": {
"recent": 751,
"previous": 617.3333333333334,
"change": 21.7,
"trend": "regressing"
},
"TTFB": {
"recent": 410.25,
"previous": 317.3333333333333,
"change": 29.3,
"trend": "regressing"
}
}
}GET/api/v1/projects/{projectId}/histogram
Page views per bucket of one metric, from 0 to 2 times its Poor threshold. Use it to see whether most page views are fast with a long tail, or slow across the board.
MCP tool: get_histogram
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
metricquery, stringrequiredOne metric.
binsquery, integerNumber of buckets, 5 to 80. Default: 40.
datequery, stringPeriod. Default: -28d.
startdatequery, stringFirst day (YYYY-MM-DD, UTC), with enddate.
enddatequery, stringLast day, included.
any dimension keyquery, stringLimits the page views to a value of that dimension, for example d=mobile. GET /api/v1/dimensions lists the keys.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/histogram?date=-7d&metric=LCP"AnswerJSON
{
"metric": "LCP",
"upper": 8000,
"buckets": [
148,
172,
142,
80,
39,
27,
18,
12,
13,
8,
8,
6,
7,
2,
6,
1,
4,
1,
0,
3,
0,
0,
0,
1,
1,
0,
0,
0,
0,
0,
0,
0,
0,
2,
0,
0,
0,
0,
0,
0,
2
],
"total": 703,
"count": 703
}GET/api/v1/projects/{projectId}/phases
The sub-phases of LCP, INP or TTFB, each with its page views and percentiles. Each sub-phase is its own percentile, so the sub-phases do not add up to the metric.
MCP tool: get_phases
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
metricquery, stringOne metric. Default: LCP.
datequery, stringPeriod. Default: -28d.
startdatequery, stringFirst day (YYYY-MM-DD, UTC), with enddate.
enddatequery, stringLast day, included.
comparequery, 1 or 0Also read the period before into prev.
any dimension keyquery, stringLimits the page views to a value of that dimension, for example d=mobile. GET /api/v1/dimensions lists the keys.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/phases?date=-7d&metric=LCP"AnswerJSON
{
"metric": "LCP",
"stats": {
"TTFB": {
"count": 753,
"p": {"p50": 137, "p75": 354, "p80": 414, "p90": 827, "p95": 1485},
"shares": [0.8950863213811421, 0.06905710491367867, 0.03585657370517925],
"prev": null
},
"LOADDELAY": {
"count": 703,
"p": {"p50": 0, "p75": 46, "p80": 62, "p90": 104, "p95": 159},
"shares": [0.9871977240398293, 0.005689900426742556, 0.007112375533428139],
"prev": null
},
"LOADTIME": {
"count": 703,
"p": {"p50": 0, "p75": 72, "p80": 101, "p90": 249, "p95": 383},
"shares": [0.9502133712660028, 0.0369843527738265, 0.012802275960170695],
"prev": null
},
"RENDERDELAY": {
"count": 703,
"p": {"p50": 126, "p75": 256, "p80": 307, "p90": 432, "p95": 566},
"shares": [0.8805120910384068, 0.085348506401138, 0.03413940256045522],
"prev": null
},
"LCP": {
"count": 703,
"p": {"p50": 452, "p75": 756, "p80": 892, "p90": 1526, "p95": 2220},
"shares": [0.9615931721194879, 0.02987197724039825, 0.008534850640113834],
"prev": null
}
}
}GET/api/v1/projects/{projectId}/values
The values a dimension has in the period with their page views (count), most page views first. Use it to find the exact URL, selector or code before you filter on it.
MCP tool: get_values
Parameters
projectIdpath, stringrequiredThe id of the site. The list of sites gives it.
dimensionquery, stringrequiredThe dimension to list. A key from filters.
searchquery, stringOnly values that contain this text (case does not matter).
limitquery, integerMost values.
datequery, stringPeriod. Default: -28d.
startdatequery, stringFirst day (YYYY-MM-DD, UTC), with enddate.
enddatequery, stringLast day, included.
any dimension keyquery, stringLimits the page views to a value of that dimension, for example d=mobile. GET /api/v1/dimensions lists the keys.
curl -H "Authorization: Bearer cdk_your_key" \
"https://app.coredash.app/api/v1/projects/your_project_id/values?date=-7d&dimension=ff"AnswerJSON
{
"dimension": "ff",
"values": [{"value": "pagespeed", "views": 134, "count": 134}]
}GET/api/v1/projects/{projectId}/views
The Explore views of the site: the standard views the user did not hide, and the views the team saved, with their pins.
MCP tool: list_views
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/views"AnswerJSON
{
"views": [
{
"id": "std-pages-mobile",
"name": "Pages on mobile",
"query": "metrics=LCP,INP,CLS&by=ff&view=table&d=mobile",
"standard": true,
"pinnedTeam": true,
"pinnedMe": false,
"mine": false
}
]
}One API key for every client site
Your API key reads every site you own or are a guest on, so one report script covers all your clients. You make it under Account > API keys. See also agency pricing.
The rest of the CoreDash API
- Installing CoreDashThe snippet, or the WordPress plugin.
- The CoreDash APIGetting a key, the errors and the limits per plan.
- The Core Web Vitals MCP serverConnecting your AI, and every tool it gets.
- The issues APIThe issues CoreDash finds, and the releases and budgets you add.
- Core Web Vitals in CI/CDChecks on every release.
- The CrUX API in CoreDashGoogle's Chrome data next to yours.
Frequently asked questions
Is this the same data as the CoreDash dashboard?
Yes. The app's pages call these same reads, so the API gives the number on screen for the same filters and period. Put the query string of a page in the app (d, aggfunc, date) on the API call and you get that view as JSON; add compare=1 for the period before.
Is it the same as the CrUX API?
No. Google's CrUX API gives a p75 and the Good, Needs improvement and Poor shares per origin or popular URL, per device class, from Chrome users, over a rolling 28 days. The RUM API is a real user monitoring API: it reads every pageview the CoreDash tracker measured on your site and splits it by any of the 40 dimensions, down to the INP element. For Google's numbers next to yours, see the CrUX API in CoreDash.
Is this the same as Google's web-vitals library?
No. The web-vitals library and PerformanceObserver measure inside one visitor's browser. On your site the CoreDash tracker does that measuring, and this web vitals API reads the results over HTTP, for all your visitors at once.
Which metrics and percentiles can I ask for?
LCP, INP, CLS, FCP and TTFB, at p50, p75, p80, p90 and p95; the default is p75. GET /api/v1/projects/{projectId}/phases splits LCP, INP and TTFB into their sub-phases. Each sub-phase is its own percentile, so the sub-phases do not add up to the metric. Good is up to 2,500 ms for LCP, 200 ms for INP and 0.1 for CLS; Poor is above 4,000 ms, 500 ms and 0.25.
How far back can I query?
56 days: CoreDash keeps every pageview that long, and any period inside that window works. The presets for date are -6h, today, -1d, -7d, -28d and -56d; the default is -28d. For whole days, send startdate and enddate (UTC); for an exact stretch, from and to.
How many calls can I make?
60 per minute per key by default, up to 960 on the largest plans. Go over it and the answer says how long to wait, in Retry-After. The limits per plan are on the API page.
Can I write data, or only read?
Both, on two pages. The calls on this page read. On the issues API, a Read and write key adds releases, notes and budgets; any owner's key posts a release from CI.
Does the RUM API cost extra?
No. The API and the MCP server come with every plan except Starter, and with every running trial. You need a CoreDash key (the API page says how to get one); MCP clients can also sign in with OAuth.