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

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

CoreDash 收集访问您网站的真实用户的 Core Web Vitals。该 API 允许您从任何工具、脚本或 AI 代理访问这些相同的数据。三个工具，JSON 进，JSON 出。

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

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

但您不需要 AI 代理。一个 curl 命令也同样有效。

身份验证

每个请求都需要在 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 为 2450ms 且 61% 为 good（良好）意味着大多数用户的体验都不错，但是长尾数据拉低了 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 }
        }
      }
    }
  ]
}

移动端为 3200ms，桌面端为 1800ms。总体聚合数据显示为 2500ms，您可能会想“虽然不是很好，但也不算太糟”。而分组视图则展示了真实情况：桌面端没问题，移动端需要优化。

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

组合使用 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 使用 250ms，INP 使用 25ms，CLS 使用 0.025，FCP 使用 200ms，TTFB 使用 125ms。

这有助于了解您的数据形态。2400ms 的 p75 可能意味着大多数用户都在 2400ms 左右，也可能意味着 60% 的用户在 1000ms 以下，而大量缓慢的移动端流量拉长了尾部。直方图会告诉您具体是哪种情况。

Dimensions（维度）

在 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 最差？”之类的问题。

速率限制 (Rate limits)

限制为每个项目每天的请求量，并在 UTC 时间午夜重置。

对于手动探索和 AI 辅助调试，试用计划中的 150 次请求已经足够。如果您在 CI 中运行自动监控，付费计划每天可提供 500 次。

错误处理

错误会作为 JSON-RPC 错误对象返回：

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

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