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 コマンドでも同様に機能します。

エージェンシーを運営している場合や、1つのアカウントから多くのプロジェクトを管理している場合はどうでしょうか。マスターキーを使用してプロジェクトを作成、更新、削除し、単一のキーですべてのプロジェクトにわたってデータを取得する別の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フィールドには任意の数字または文字列を指定できます。これはレスポンスでエコーバックされます。ツールは3つあります：get_metrics、get_timeseries、およびget_histogram。

get_metrics: 現在のパフォーマンス

good/improve/poorの評価とともに現在のCore Web Vitalsの値を返します。これは、「現在の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ミリ秒で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 }
        }
      }
    }
  ]
}

モバイルは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%以上悪化）です。これが、タイムシリーズエンドポイントを自動モニタリングに役立たせる理由です。状況が悪化しているかどうかを知るために、データポイントを自分で解析する必要はありません。

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は250ミリ秒、INPは25ミリ秒、CLSは0.025、FCPは200ミリ秒、TTFBは125ミリ秒を使用します。

これは、データの形状を理解するのに役立ちます。p75が2400ミリ秒の場合、ほとんどのユーザーが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%がしきい値を下回っていれば、合格となります。

MCPサーバーとしてのAPIの使用

この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日あたりで設定されており、協定世界時（UTC）の深夜0時にリセットされます。

Trialプランの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時のリセットを待つか、プランをアップグレードしてください。