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 verilerini toplar. API, aynı verilere herhangi bir araç, script veya AI aracısından erişmenizi sağlar. Üç araç, JSON girişi, JSON çıkışı.

En ilgi çekici kullanım durumu: AI'nizi bağlamak. CoreDash API, Model Context Protocol (MCP) ile aynı protokolü kullanır, bu da Claude, Cursor ve Windsurf gibi AI araçlarının gerçek kullanıcı verilerinizi doğrudan sorgulayabileceği anlamına gelir. AI'nize "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 aracıdır. Bunu mümkün kılan şey API'dir.

Ancak bir AI aracısına ihtiyacınız yok. Bir curl komutu da aynı şekilde işe yarar.

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, sonrasında Connect Your AI seçeneğine 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ılmıştır. Birden fazla anahtar oluşturabilir ve bunları aynı sayfadan iptal edebilirsiniz.

İstek formatı

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

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

İstek gövdesi şu şekildedir:

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

Gerçek veri, text alanının içindeki bir JSON dizesidir. Ayrıştırıldığında şu şekilde görünür:

{
  "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 girdiğini söyler. Bu genellikle sadece p75 değerinden daha faydalıdır. %61'i good (iyi) 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 3200 ms, masaüstü 1800 ms. Toplam değer 2500 ms gösterir ve "harika değil, ama çok da kötü değil" diye düşünebilirsiniz. Gruplandırılmış görünüm ise gerçek hikayeyi gösterir: masaüstü gayet iyi, mobilin üzerinde çalışılması gerekiyor.

Örnek: mobilde belirli bir sayfaya filtrele

Tam olarak ilgilendiğiniz trafiğe daraltmak için filters parametrelerini 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çindeki performans

Otomatik trend tespiti ile zaman içinde gruplandırılmış metrik değerlerini döndürür. Bu, "LCP değerim kötüleşti mi?" ve "bu dağıtım 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, dönemin ikinci yarısını ilk yarısıyla karşılaştırır. Trend değerleri improving (%5'ten daha iyi), stable (%5 içinde) veya regressing (%5'ten daha kötü) ş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ımlarla 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 (metrics değil) alır. İstek başına bir metrik.

Örnek: mobildeki 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ü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 değeri to: null şeklindedir çünkü ucu açık bir kuyruktur.

Grup genişlikleri metrik başına sabittir: LCP 250 ms kullanır, INP 25 ms kullanır, CLS 0.025 kullanır, FCP 200 ms kullanır, TTFB 125 ms 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ş bir mobil trafik kitlesinin kuyruğu çektiği anlamına gelebilir. Histogram hangisi olduğunu size söyler.

Boyutlar

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

Genel

Cihaz ve ağ

Metrik ilişkilendirme

Bu boyutlar size bir metrik değerine neyin neden olduğunu söyler. Sayfalarınızda hangi öğelerin LCP olduğunu görmek için lcpel'e göre gruplandırın. En kötü INP'yi üreten etkileşimleri bulmak için inpel'e göre gruplandırı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ı tamamen uyumlu bir MCP sunucusudur. AI aracınız MCP'yi (Claude Code, Cursor, Windsurf ve diğerleri) destekliyorsa, doğrudan bağlayabilirsiniz. AI daha sonra araçlar olarak get_metrics, get_timeseries ve get_histogram'a erişim sağlar ve herhangi bir görüşmenin 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 bağlayabilirsiniz. MCP istemcinizi API anahtarınızla https://app.coredash.app/api/mcp adresine yönlendirin; AI'niz "mobilde en kötü INP'ye sahip sayfalar hangileri?" gibi soruları tahmin yürütmek yerine gerçek saha verilerini kullanarak yanıtlayabilir.

Hız sınırları

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

Trial planındaki 150 istek, manuel keşif ve AI 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 sunar.

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

Eğer -32001 alırsanız, anahtarınızın cdk_ ile başladığını ve iptal etmediğinizi kontrol edin. -32002 alırsanız, günlük sınıra ulaşmışsınızdır. UTC gece yarısı sıfırlamasını bekleyin veya planınızı yükseltin.