CoreDash API: リアルユーザーのCore Web Vitalsデータをクエリする

パフォーマンスデータを必要な場所どこでも

CoreDashは、サイトを訪問するリアルユーザーからCore Web Vitalsを収集します。APIを使用すると、任意のツール、スクリプト、またはAIエージェントからその同じデータにアクセスできます。3つのツール、JSON入力、JSON出力。

最も興味深いユースケース：AIの接続。CoreDash APIはModel Context Protocol (MCP)と同じプロトコルを使用しているため、Claude、Cursor、WindsurfなどのAIツールはリアルユーザーデータを直接クエリできます。AIに「モバイルでLCPが遅いのはなぜか？」と尋ねると、実際のフィールドデータを取得して回答します。

これを基盤としてCWV Superpowersを構築しました。これは、CoreDashのフィールドデータとChrome DevToolsを組み合わせてCore Web Vitalsの問題を診断・修正するAIエージェントです。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フィールドには任意の数値または文字列を指定できます。これはレスポンスでエコーバックされます。ツールは3つあります。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ではない）を受け取ります。リクエストごとに1つの指標です。

例: モバイルでの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を使用します。

これはデータの形状を理解するのに役立ちます。p75が2400msの場合、ほとんどのユーザーが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クライアントでAPIキーを使用してhttps://app.coredash.app/api/mcpを指定すると、AIは推測ではなく実際のフィールドデータを使用して「モバイルで最悪のINPを持つページはどれか？」といった質問に答えることができます。

レート制限

制限は1プロジェクトあたり1日単位で、UTCの深夜0時にリセットされます。

トライアルプランの150リクエストは、手動での調査やAI支援によるデバッグには十分です。CIで自動モニタリングを実行している場合、有料プランでは1日あたり500リクエストが提供されます。

エラー処理

エラーはJSON-RPCエラーオブジェクトとして返されます。

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

-32001を受け取った場合は、キーがcdk_で始まっていること、および失効していないことを確認してください。-32002を受け取った場合は、1日の制限に達しています。UTCの深夜0時のリセットを待つか、プランをアップグレードしてください。