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が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ではない) を受け取る。1リクエストにつき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セットアップに接続することも可能である。APIキーを使用してMCPクライアントを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時のリセットを待つか、プランをアップグレードする必要がある。