CoreDash API: Gerçek Kullanıcı Core Web Vitals Verilerini Sorgula

Performans verilerin, ihtiyacın olan her yerde

CoreDash siteni ziyaret eden gerçek kullanıcılardan Core Web Vitals verilerini toplar. API, aynı verilere herhangi bir araç, betik veya yapay zeka ajanından erişmeni sağlar. Üç araç, JSON girer, JSON çıkar.

En ilginç kullanım senaryosu: Yapay zekanı bağlamak. CoreDash API, Model Context Protocol (MCP) ile aynı protokolü kullanır; bu da Claude, Cursor ve Windsurf gibi yapay zeka araçlarının gerçek kullanıcı verilerini doğrudan sorgulayabileceği anlamına gelir. Yapay zekana "mobilde LCP'm neden yavaş?" diye sor, yanıtlamak için gerçek field data'yı çeksin.

Bunun üzerine CWV Superpowers'ı geliştirdik. Bu, Core Web Vitals sorunlarını teşhis etmek ve düzeltmek için CoreDash field data'nı Chrome DevTools ile birleştiren bir yapay zeka ajanıdır. Bunu mümkün kılan ise API'dir.

Ancak bir yapay zeka ajanına ihtiyacın yok. Bir curl komutu da aynı derecede iş görür.

Bir ajans mı yönetiyorsun yoksa tek bir hesaptan birçok projeyi mi kontrol ediyorsun? Projeleri oluşturmak, güncellemek, silmek ve tek bir anahtarla hepsinden veri çekmek için bir master key kullanan ayrı bir Agency API mevcut. Bu sayfanın geri kalanı proje bazlı veri API'sini kapsar.

Kimlik Doğrulama

Her istek, Authorization başlığında bir API anahtarı gerektirir:

Authorization: Bearer cdk_YOUR_API_KEY

Anahtar almak için:

1. app.coredash.app adresinden giriş yap
2. Projene git, ardından AI Insights ve sonrasında Connect Your AI adımlarını takip et
3. Create API Key butonuna tıkla ve anahtarı kopyala. Sadece bir kez gösterilir.

Anahtarlar cdk_ ile başlar ve tek bir projeyle sınırlıdır. Aynı sayfadan birden fazla anahtar oluşturabilir ve bunları iptal edebilirsin.

İstek formatı

API, JSON-RPC 2.0 kullanır. Her istek şuraya yapılan bir POST isteğidir:

https://app.coredash.app/api/mcp

İstek gövdesi şuna benzer:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_metrics",
    "arguments": { }
  }
}

id alanı herhangi bir sayı veya string olabilir. Yanıtta aynen geri döner. Üç araç mevcuttur: get_metrics, get_timeseries ve get_histogram.

get_metrics: güncel performans

good/improve/poor derecelendirmeleriyle güncel Core Web Vitals değerlerini döndürür. Bu, "şu anda LCP'm kaç?" gibi sorular için kullandığın araçtır.

Parametreler

Örnek: tüm metrikleri al

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": {}
    }
  }'

Ham yanıt bir JSON-RPC sarmalayıcısıdır:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{ ... JSON string ... }"
    }]
  }
}

Asıl veri, text alanının içindeki bir JSON string'dir. Ayrıştırılmış hali şuna benzer:

{
  "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 objesi, gerçek sayfa yüklenmelerinin yüzde kaçının hangi derecelendirmeye girdiğini söyler. Bu genellikle tek başına p75 değerinden daha kullanışlıdır. %61'i good olan 2450 ms'lik bir LCP, çoğu kullanıcının sorunsuz bir deneyim yaşadığını, ancak kuyruğun p75'i kötüleştirdiğini gösterir.

Örnek: mobil ve masaüstü LCP'yi karşılaştır

Sonuçları herhangi bir boyuta göre bölmek için group parametresini kullan. LCP sorununun mobilden kaynaklanıp kaynaklanmadığını bu şekilde anlarsın:

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"
      }
    }
  }'

Ayrıştırılmış yanıt:

{
  "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 }
        }
      }
    }
  ]
}

Mobil 3200 ms, masaüstü 1800 ms. Genel toplam 2500 ms gösterecekti ve sen "ne iyi ne kötü" diye düşünecektin. Gruplandırılmış görünüm asıl resmi ortaya koyuyor: Masaüstü iyi, mobilin ise elden geçmesi gerek.

Örnek: mobilde belirli bir sayfayı filtrele

Tam olarak ilgilendiğin trafiğe daraltmak için filters parametrelerini birleştir:

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: zaman içindeki performans

Zaman içinde gruplandırılmış metrik değerlerini otomatik trend tespitiyle döndürür. Bu aracı "LCP'm kötüleşti mi?" veya "son deploy regresyonu düzeltti mi?" gibi durumlar için kullanırsın.

Parametreler

Örnek: son 7 güne ait LCP trendi

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"
      }
    }
  }'

Ayrıştırılmış yanıt:

{
  "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 alanı, periyodun ikinci yarısını ilk yarısıyla karşılaştırır. Trend değerleri improving (%5'ten fazla iyileşme), stable (%5 içinde kalma) veya regressing (%5'ten fazla kötüleşme) şeklindedir. Bu durum, timeseries endpoint'ini otomatik izleme için kullanışlı kılar: İşlerin kötüye gidip gitmediğini anlamak için veri noktalarını tek tek ayrıştırmana gerek kalmaz.

get_histogram: dağılım şekli

Tek bir metriğin dağılımını, aralık başına sayım içeren ~40 grup (bucket) olarak döndürür. p75 iyi görünse de uzun bir kuyruktan şüphelendiğinde veya performans verilerinin tam şeklini görmek istediğinde bu aracı kullanırsın.

Parametreler

Not: get_metrics aksine, bu araç tek bir metric parametresi alır (metrics değil). İstek başına tek bir metrik gönderilir.

Örnek: mobilde LCP dağılımı

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"
      }
    }
  }'

Ayrıştırılmış yanıt:

{
  "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
}

Her grubun (bucket) from/to sınırları, o aralıktaki tahmini sayfa yüklenme sayısını veren bir count değeri ve grubun Core Web Vitals eşiklerine göre konumunu gösteren bir rating değeri bulunur. Son grup, açık uçlu kuyruk olduğu için to: null değerine sahiptir.

Grup genişlikleri metrik başına sabittir: LCP 250 ms, INP 25 ms, CLS 0,025, FCP 200 ms, TTFB ise 125 ms kullanır.

Bu durum, verilerinin şeklini anlamak için kullanışlıdır. 2400 ms'lik bir p75 değeri, çoğu kullanıcının 2400 ms civarında olduğu anlamına gelebileceği gibi, %60'ının 1000 ms'nin altında olduğu ve yavaş bir mobil trafik grubunun kuyruğu uzattığı anlamına da gelebilir. Histogram hangisinin doğru olduğunu gösterir.

Boyutlar

Bu anahtarları filters içinde veya group değeri olarak kullan. Filtreleme, verileri belirli bir segmente daraltır. Gruplama ise segmentleri yan yana karşılaştırabilmen için sonuçları böler.

Genel

Cihaz ve ağ

Metrik ilişkilendirme

Bu boyutlar, metrik değerine neyin neden olduğunu gösterir. Sayfalarında hangi öğelerin LCP olduğunu görmek için lcpel ile grupla. En kötü INP'ye yol açan etkileşimleri bulmak için ise inpel ile gruplama yap.

Filtre örnekleri

{ "d": "mobile" }
{ "ff": "/checkout", "d": "desktop" }
{ "cc": "US", "browser": "Chrome" }
{ "u": "[neq]*/admin/*" }

Metrikler referansı

Varsayılan persentil p75'tir. Google, Core Web Vitals sıralaması için bunu kullanır. Sayfa yüklenmelerinin %75'i eşiğin altındaysa testi geçersin.

API'yi bir MCP sunucusu olarak kullanmak

API endpoint'i tamamen uyumlu bir MCP sunucusudur. Yapay zeka aracın MCP'yi destekliyorsa (Claude Code, Cursor, Windsurf ve diğerleri), doğrudan bağlayabilirsin. Böylece yapay zeka, get_metrics, get_timeseries ve get_histogram araçlarına erişebilir ve herhangi bir sohbetin parçası olarak field data'nı sorgulayabilir.

CWV Superpowers bu şekilde çalışır: CoreDash'e MCP üzerinden bağlanır, gerçek kullanıcı verilerini çeker, siteni Chrome'da açar ve yavaş bir metriğin kesin nedenini izler. API, "production'da ne oluyor" kısmını sağlar, Chrome ise "neden oluyor" kısmını sunar.

MCP sunucusunu kendi yapay zeka kurulumuna da bağlayabilirsin. MCP istemcini API anahtarınla birlikte https://app.coredash.app/api/mcp adresine yönlendir; yapay zekan tahmin yürütmek yerine gerçek field data'yı kullanarak "mobilde en kötü INP hangi sayfalarda?" gibi soruları yanıtlayabilir.

Rate limitleri

Limitler proje başına günlüktür ve gece yarısı (UTC saatine göre) sıfırlanır.

Trial planındaki 150 istek, manuel inceleme ve yapay zeka destekli hata ayıklama (debugging) için fazlasıyla yeterli. Eğer CI süreçlerinde otomatik izleme çalıştırıyorsan, ücretli planlar sana günlük 500 istek sunar.

Hata yönetimi

Hatalar, JSON-RPC hata objeleri olarak döner:

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

Eğer -32001 alırsan, anahtarının cdk_ ile başlayıp başlamadığını ve onu iptal edip etmediğini kontrol et. -32002 alırsan günlük limite ulaşmışsın demektir. UTC gece yarısı sıfırlamasını bekle veya planını yükselt.