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 以下，而一部分缓慢的移动端流量正在拉长长尾。直方图能告诉您具体是哪种情况。

维度

在 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 设置。将您的 MCP 客户端指向 https://app.coredash.app/api/mcp 并带上您的 API 密钥，您的 AI 就可以使用实际现场数据而不是靠猜测来回答诸如“移动端上哪些页面的 INP 最差？”之类的问题。

速率限制

限制是针对每个项目每天设定的，并在午夜 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 时间重置或升级您的套餐。