CoreDash API：查询真实用户 Core Web Vitals 数据

随时随地获取您的性能数据

CoreDash 从访问您网站的真实用户那里收集 Core Web Vitals 数据。该 API 允许您从任何工具、脚本或 AI agent 访问相同的数据。提供三个工具，JSON 输入，JSON 输出。

最有趣的用例：连接您的 AI。CoreDash API 使用与 Model Context Protocol (MCP) 相同的协议，这意味着像 Claude、Cursor 和 Windsurf 这样的 AI 工具可以直接查询您的真实用户数据。问您的 AI“为什么我的移动端 LCP 慢？”，它就会提取实际的现场数据来回答。

我们在此基础上构建了 CWV Superpowers。它是一个 AI agent，将您的 CoreDash 现场数据与 Chrome DevTools 结合起来，以诊断和修复 Core Web Vitals 问题。正是该 API 使这一切成为可能。

但您不需要 AI agent。curl 命令同样适用。

运营代理机构或从一个账户管理许多项目？我们提供一个独立的 Agency API，它使用主密钥来创建、更新和删除项目，并使用单个密钥提取所有项目的数据。本页面的其余部分涵盖了每个项目的数据 API。

身份验证

每个请求都需要在 Authorization 标头中包含一个 API 密钥：

Authorization: Bearer cdk_YOUR_API_KEY

获取密钥的方法：

1. 登录 app.coredash.app
2. 进入您的项目，然后点击 AI Insights，接着点击 Connect Your AI
3. 点击 Create API Key 并复制它。它只显示一次。

密钥以 cdk_ 开头，并且作用域限定为单个项目。您可以创建多个密钥并在同一页面上撤销它们。

请求格式

该 API 使用 JSON-RPC 2.0。每个请求都是一个 POST 请求，目标地址为：

https://app.coredash.app/api/mcp

请求正文如下所示：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_metrics",
    "arguments": { }
  }
}

id 字段可以是任何数字或字符串。它会在响应中被原样返回。提供三个工具：get_metrics、get_timeseries 和 get_histogram。

get_metrics：当前性能

返回当前的 Core Web Vitals 值以及良好（good）/需要改进（improve）/较差（poor）的评级。这是您在遇到诸如“我现在的 LCP 是多少？”这类问题时使用的工具。

参数

示例：获取所有指标

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_metrics",
      "arguments": {}
    }
  }'

原始响应是一个 JSON-RPC 包装器：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{ ... JSON string ... }"
    }]
  }
}

实际数据是位于 text 字段内的 JSON 字符串。解析后，它看起来像这样：

{
  "period": "last 31 days",
  "percentile": "p75",
  "metrics": {
    "LCP": {
      "value": 2450,
      "unit": "ms",
      "rating": "improve",
      "distribution": { "good": 61.2, "improve": 22.4, "poor": 16.4 }
    },
    "INP": {
      "value": 180,
      "unit": "ms",
      "rating": "good",
      "distribution": { "good": 82.1, "improve": 12.3, "poor": 5.6 }
    },
    "CLS": {
      "value": 0.08,
      "unit": "",
      "rating": "good",
      "distribution": { "good": 74.5, "improve": 18.2, "poor": 7.3 }
    }
  }
}

distribution 对象告诉您有多少比例的实际页面加载落在每个评级中。这通常比单独的 p75 值更有用。LCP 为 2450 毫秒且 61% 为“良好”，这意味着大多数用户都有不错的体验，但是长尾数据拉低了 p75 的表现。

示例：比较移动端与桌面端的 LCP

使用 group 参数可以按任何维度拆分结果。通过这种方式，您可以找出您的 LCP 问题是否是移动端问题：

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_metrics",
      "arguments": {
        "metrics": "LCP",
        "group": "d",
        "date": "-7d"
      }
    }
  }'

解析后的响应：

{
  "period": "last 7 days",
  "percentile": "p75",
  "groupedBy": "d",
  "groupName": "Device Type",
  "segments": [
    {
      "segment": "mobile",
      "value": "mobile",
      "metrics": {
        "LCP": {
          "value": 3200, "unit": "ms", "rating": "improve",
          "distribution": { "good": 52.3, "improve": 28.1, "poor": 19.6 }
        }
      }
    },
    {
      "segment": "desktop",
      "value": "desktop",
      "metrics": {
        "LCP": {
          "value": 1800, "unit": "ms", "rating": "good",
          "distribution": { "good": 78.5, "improve": 15.2, "poor": 6.3 }
        }
      }
    }
  ]
}

移动端为 3200 毫秒，桌面端为 1800 毫秒。汇总数据可能显示为 2500 毫秒，您可能会认为“不算好，但也不算太糟”。分组视图则展示了真实情况：桌面端没问题，移动端需要优化。

示例：在移动端过滤到特定页面

结合 filters 来缩小范围，精确找到您关心的流量：

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_metrics",
      "arguments": {
        "metrics": "LCP,CLS",
        "filters": { "ff": "/checkout", "d": "mobile" },
        "date": "-7d"
      }
    }
  }'

get_timeseries：随时间变化的性能

返回随时间分桶的指标值，并具有自动趋势检测功能。这是您在遇到诸如“我的 LCP 变差了吗？”以及“那次部署是否修复了性能下降？”这类问题时使用的工具。

参数

示例：过去 7 天的 LCP 趋势

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_timeseries",
      "arguments": {
        "metrics": "LCP",
        "date": "-7d",
        "granularity": "day"
      }
    }
  }'

解析后的响应：

{
  "period": "last 7 days",
  "percentile": "p75",
  "granularity": "day",
  "dataPoints": 7,
  "timeseries": [
    { "date": "2026-03-10T00:00:00.000Z", "LCP": { "value": 2600, "unit": "ms", "rating": "improve" } },
    { "date": "2026-03-11T00:00:00.000Z", "LCP": { "value": 2450, "unit": "ms", "rating": "improve" } },
    { "date": "2026-03-12T00:00:00.000Z", "LCP": { "value": 2300, "unit": "ms", "rating": "good" } }
  ],
  "summary": {
    "LCP": {
      "recent": 2350,
      "previous": 2680,
      "change": -12.3,
      "trend": "improving",
      "unit": "ms"
    }
  }
}

summary 将期间的后半部分与前半部分进行比较。趋势值包括 improving（改善超过 5%）、stable（在 5% 以内）或 regressing（恶化超过 5%）。这就是 timeseries 接口对于自动化监控非常有用的原因：您无需自己解析数据点即可知道情况是否正在恶化。

get_histogram：分布形状

返回单一指标的分布，大约有 40 个桶，其中包含每个范围的计数。当 p75 看起来不错，但您怀疑存在长尾现象时，或者当您想查看性能数据的完整形状时，您就可以使用此工具。

参数

注意：与 get_metrics 不同，它接受单一的 metric（而不是 metrics）。每个请求一个指标。

示例：移动端的 LCP 分布

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "get_histogram",
      "arguments": {
        "metric": "LCP",
        "filters": { "d": "mobile" },
        "date": "-7d"
      }
    }
  }'

解析后的响应：

{
  "period": "last 7 days",
  "metric": "LCP",
  "unit": "ms",
  "filters": { "d": "mobile" },
  "buckets": [
    { "from": 0, "to": 250, "count": 1250, "rating": "good" },
    { "from": 250, "to": 500, "count": 3400, "rating": "good" },
    { "from": 500, "to": 750, "count": 2800, "rating": "good" },
    { "from": 2500, "to": 2750, "count": 890, "rating": "improve" },
    { "from": 4000, "to": 4250, "count": 120, "rating": "poor" },
    { "from": 9750, "to": null, "count": 15, "rating": "poor" }
  ],
  "total": 45000
}

每个桶都有 from/to 边界，该范围内估计页面加载的 count（计数），以及基于该桶相对于 Core Web Vitals 阈值的位置得出的 rating（评级）。最后一个桶包含 to: null，因为它是开放式的长尾。

每个指标的桶宽度是固定的：LCP 使用 250 毫秒，INP 使用 25 毫秒，CLS 使用 0.025，FCP 使用 200 毫秒，TTFB 使用 125 毫秒。

这有助于了解数据的形状。2400 毫秒的 p75 可能意味着大多数用户在 2400 毫秒左右，或者可能意味着 60% 的用户在 1000 毫秒以内，而一部分缓慢的移动端流量正在拉长尾部。直方图可以告诉您具体是哪种情况。

维度

在 filters 中或作为 group 值使用这些键。过滤可将数据缩小到特定的细分受众群。分组可拆分结果，以便您可以并排比较不同的细分受众群。

通用

设备与网络

指标归因

这些维度告诉您是什么导致了某个指标值。按 lcpel 分组可以查看您的页面中有哪些元素成为了 LCP。按 inpel 分组可以找到产生最差 INP 的交互。

过滤示例

{ "d": "mobile" }
{ "ff": "/checkout", "d": "desktop" }
{ "cc": "US", "browser": "Chrome" }
{ "u": "[neq]*/admin/*" }

指标参考

默认的百分位数是 p75。这也是 Google 用于 Core Web Vitals 排名的标准。如果您的页面加载有 75% 低于该阈值，您就合格了。

将 API 用作 MCP 服务器

该 API 接口是一个完全兼容的 MCP 服务器。如果您的 AI 工具支持 MCP（例如 Claude Code、Cursor、Windsurf 等），您可以直接连接它。然后，AI 将有权访问 get_metrics、get_timeseries 和 get_histogram 这几个工具，并可以作为任何对话的一部分查询您的现场数据。

这正是 CWV Superpowers 的工作原理：它通过 MCP 连接到 CoreDash，提取您的真实用户数据，在 Chrome 中打开您的网站，并追踪指标变慢的根本原因。API 提供了“生产环境中正在发生什么”的部分，而 Chrome 提供了“为什么会发生”的部分。

您还可以将 MCP 服务器连接到您自己的 AI 设置。使用您的 API 密钥将您的 MCP 客户端指向 https://app.coredash.app/api/mcp，您的 AI 就可以使用实际的现场数据而不是靠猜测来回答诸如“移动端哪些页面的 INP 最差？”之类的问题。

速率限制

限制按项目、按天计算，并在 UTC 时间午夜重置。

试用版的 150 次请求足以满足手动探索和 AI 辅助调试的需求。如果您在 CI 中运行自动化监控，付费计划每天可为您提供 500 次请求。

错误处理

错误会以 JSON-RPC 错误对象的形式返回：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32001, "message": "Invalid or revoked API key." }
}

如果您遇到 -32001，请检查您的密钥是否以 cdk_ 开头，以及您是否已将其撤销。如果您遇到 -32002，说明您已达到每日限制。请等待 UTC 时间午夜重置或升级您的计划。