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

Performans verileriniz, ihtiyacınız olan her yerde

CoreDash, sitenizi ziyaret eden gerçek kullanıcılardan Core Web Vitals toplar. API, aynı verilere herhangi bir araç, script veya AI ajanından erişmenizi sağlar. Üç araç, JSON girer, JSON çıkar.

En ilginç kullanım senaryosu: yapay zekanızı bağlamak. CoreDash API, Model Context Protocol (MCP) ile aynı protokolü kullanır, yani Claude, Cursor ve Windsurf gibi AI araçları gerçek kullanıcı verilerinizi doğrudan sorgulayabilir. AI'ınıza "mobilde LCP neden yavaş?" diye sorun ve cevaplamak için gerçek saha verilerini çeksin.

Bunun üzerine CWV Superpowers'ı inşa ettik. Bu, Core Web Vitals sorunlarını teşhis etmek ve düzeltmek için CoreDash saha verilerinizi Chrome DevTools ile birleştiren bir AI ajanıdır. Bunu mümkün kılan şey API'dir.

Ancak bir AI ajanına ihtiyacınız yok. Bir curl komutu da aynı derecede iyi çalışır.

Kimlik Doğrulama

Her isteğin Authorization başlığında bir API anahtarına ihtiyacı vardır:

Authorization: Bearer cdk_YOUR_API_KEY

Bir anahtar almak için:

1. app.coredash.app adresinden giriş yapın
2. Projenize gidin, ardından AI Insights'a, sonrasında Connect Your AI'a tıklayın
3. Create API Key düğmesine tıklayın ve kopyalayın. Sadece bir kez gösterilir.

Anahtarlar cdk_ ile başlar ve tek bir projeyle sınırlandırılır. Birden fazla anahtar oluşturabilir ve aynı sayfadan bunları iptal edebilirsiniz.

İstek formatı

API, JSON-RPC 2.0 kullanır. Her istek şuraya yapılan bir POST işlemidir:

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 dize olabilir. Yanıtta geri döndürülür. Üç araç vardır: get_metrics, get_timeseries ve get_histogram.

get_metrics: mevcut performans

Mevcut Core Web Vitals değerlerini iyi/geliştirilmeli/kötü (good/improve/poor) derecelendirmeleriyle döndürür. Bu, "şu anda LCP değerim nedir?" türündeki sorular için kullandığınız araçtır.

Parametreler

Örnek: tüm metrikleri getir

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

Gerçek veri, text alanının içindeki bir JSON dizesidir. Ayrıştırıldığında ş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 nesnesi, gerçek sayfa yüklemelerinin yüzde kaçının her bir derecelendirmeye düştüğünü söyler. Bu genellikle tek başına p75 değerinden daha kullanışlıdır. %61'i iyi (good) olan 2450 ms'lik bir LCP, çoğu kullanıcının iyi bir deneyim yaşadığı, ancak kuyruk kısmının p75'i aşağı çektiği anlamına gelir.

Örnek: mobil ve masaüstü LCP karşılaştırması

Sonuçları herhangi bir boyuta göre bölmek için group parametresini kullanın. LCP sorununuzun bir mobil sorunu olup olmadığını bu şekilde öğrenebilirsiniz:

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 3200ms, masaüstü 1800ms. Toplam değer 2500ms gösterecekti ve "harika değil ama korkunç da değil" diye düşünecektiniz. Gruplandırılmış görünüm asıl hikayeyi gösteriyor: masaüstü iyi, mobilin üzerinde çalışılması gerekiyor.

Örnek: mobilde belirli bir sayfayı filtreleme

Tam olarak ilgilendiğiniz trafiğe daraltmak için filters parametresini birleştirin:

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çinde performans

Otomatik trend tespitiyle birlikte zaman içinde gruplanmış metrik değerlerini döndürür. Bu, "LCP değerim kötüleşti mi?" ve "bu dağıtım (deploy) gerilemeyi düzeltti mi?" soruları için kullandığınız araçtır.

Parametreler

Örnek: son 7 gündeki 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 nesnesi, dönemin ikinci yarısını ilk yarısıyla karşılaştırır. Trend değerleri improving (%5'ten fazla iyileşme), stable (%5 aralığında) veya regressing (%5'ten fazla kötüleşme) şeklindedir. Zaman serisi uç noktasını (endpoint) otomatik izleme için yararlı kılan şey budur: işlerin kötüye gidip gitmediğini bilmek için veri noktalarını kendiniz ayrıştırmanıza gerek yoktur.

get_histogram: dağılım şekli

Tek bir metriğin dağılımını, aralık başına sayılarla birlikte ~40 grup (bucket) olarak döndürür. Bu, p75 iyi göründüğünde ancak uzun bir kuyruktan şüphelendiğinizde veya performans verilerinizin tam şeklini görmek istediğinizde kullandığınız araçtır.

Parametreler

Not: get_metrics aracının aksine, bu tek bir metric alır (metrics değil). İstek başına bir metrik.

Ö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ı, bu aralıktaki tahmini sayfa yüklemelerinin bir count değeri ve grubun Core Web Vitals eşiklerine göre nerede bulunduğuna bağlı olarak bir rating değeri vardır. Son grubun to: null değerine sahip olmasının nedeni, açık uçlu kuyruk olmasıdır.

Grup (bucket) genişlikleri metrik başına sabittir: LCP 250ms kullanır, INP 25ms kullanır, CLS 0.025 kullanır, FCP 200ms kullanır, TTFB 125ms kullanır.

Bu, verilerinizin şeklini anlamak için kullanışlıdır. 2400 ms'lik bir p75, çoğu kullanıcının 2400 ms civarında olduğu anlamına gelebilir veya %60'ının 1000 ms'nin altında olduğu ve yavaş mobil trafikten oluşan bir kısmın kuyruğu çektiği anlamına gelebilir. Histogram size hangisinin doğru olduğunu söyler.

Boyutlar (Dimensions)

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

Genel

Cihaz ve ağ

Metrik ilişkilendirme (attribution)

Bu boyutlar size bir metrik değerine nein neden olduğunu söyler. Sayfalarınızda hangi öğelerin LCP haline geldiğini görmek için lcpel değerine göre gruplayın. En kötü INP'yi üreten etkileşimleri bulmak için inpel değerine göre gruplayın.

Filtre örnekleri

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

Metrik referansı

Varsayılan yüzdelik dilim p75'tir. Google'ın Core Web Vitals sıralaması için kullandığı değer budur. Sayfa yüklemelerinizin %75'i eşiğin altındaysa, geçersiniz.

API'yi bir MCP sunucusu olarak kullanma

API uç noktası (endpoint) tamamen uyumlu bir MCP sunucusudur. AI aracınız MCP'yi destekliyorsa (Claude Code, Cursor, Windsurf ve diğerleri), doğrudan bağlayabilirsiniz. AI daha sonra get_metrics, get_timeseries ve get_histogram araçlarına erişebilir ve herhangi bir sohbetin parçası olarak saha verilerinizi sorgulayabilir.

CWV Superpowers şu şekilde çalışır: MCP aracılığıyla CoreDash'e bağlanır, gerçek kullanıcı verilerinizi çeker, sitenizi Chrome'da açar ve yavaş bir metriğin kesin nedenini izler. API "üretimde ne oluyor" kısmını sağlarken, Chrome "neden oluyor" kısmını sağlar.

Ayrıca MCP sunucusunu kendi AI kurulumunuza da bağlayabilirsiniz. MCP istemcinizi API anahtarınızla birlikte https://app.coredash.app/api/mcp adresine yönlendirin; AI'ınız "mobilde hangi sayfalar en kötü INP'ye sahip?" gibi soruları tahmin yürütmek yerine gerçek saha verilerini kullanarak cevaplayabilir.

Hız sınırları (Rate limits)

Sınırlar proje başına günlüktür ve gece yarısı UTC'de sıfırlanır.

Trial planındaki 150 istek, manuel keşif ve yapay zeka destekli hata ayıklama için fazlasıyla yeterlidir. CI'da otomatik izleme çalıştırıyorsanız, ücretli planlar size günde 500 istek hakkı verir.

Hata yönetimi

Hatalar, JSON-RPC hata nesneleri olarak geri döner:

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

-32001 alırsanız, anahtarınızın cdk_ ile başladığından ve iptal etmediğinizden emin olun. -32002 alırsanız, günlük sınıra ulaşmışsınızdır. Gece yarısı UTC sıfırlamasını bekleyin veya planınızı yükseltin.