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 在移动端很慢？”，它就会获取真实的 field data 来回答。

我们在此基础上构建了 CWV Superpowers。它是一个 AI agent，结合了你的 CoreDash field data 与 Chrome DevTools，用以诊断并修复 Core Web Vitals 问题。是该 API 让这成为可能。

但你不需要 AI agent。一个 curl 命令也同样好用。

你是在运营代理商，还是在一个账号下管理多个项目？我们提供了一个独立的 Agency API。它使用主密钥来创建、更新和删除项目，并能用单个密钥提取所有项目的数据。本页面的其余部分将介绍单项目的数据 API。

身份验证

每个请求都需要在 Authorization 请求头中携带 API key：

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 且 good 占比 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 }
        }
      }
    }
  ]
}

移动端为 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 以下，而一部分缓慢的移动端流量拉长了尾部。直方图会告诉你到底是哪种情况。

维度

在 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 作为工具来查询你的 field data。

这就是 CWV Superpowers 的工作原理：它通过 MCP 连接到 CoreDash，提取你的真实用户数据，在 Chrome 中打开你的网站，并追踪导致指标变慢的准确原因。API 提供“生产环境正在发生什么”的信息，而 Chrome 提供“为什么会发生”的答案。

你也可以将该 MCP 服务器连接到你自己的 AI 系统。只需将你的 MCP 客户端指向 https://app.coredash.app/api/mcp 并附上 API key，你的 AI 就能使用真实的 field data 来回答“移动端上哪些页面的 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 时间午夜重置，或者升级你的套餐。