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çtan, betikten veya yapay zeka 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, bu da Claude, Cursor ve Windsurf gibi yapay zeka araçlarının gerçek kullanıcı verilerinizi doğrudan sorgulayabileceği anlamına gelir. Yapay zekanıza "mobilde LCP neden yavaş?" diye sorun ve cevaplamak için gerçek saha verilerini çeker.

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

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

Bir ajans mı yönetiyorsunuz veya tek bir hesaptan birçok projeyi mi yönetiyorsunuz? Projeler oluşturmak, güncellemek ve silmek ile tek bir anahtarla tüm projelerden veri çekmek için ana anahtar kullanan ayrı bir Agency API bulunmaktadır. Bu sayfanın geri kalanı proje başına veri API'sini kapsar.

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, ardından AI Insights'a, ardından Connect Your AI'a gidin
3. Create API Key'e 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. Aynı sayfadan birden fazla anahtar oluşturabilir ve bunları iptal edebilirsiniz.

İstek formatı

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

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 yansıtı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'm nedir?" türü 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 sarıcısıdır:

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

Gerçek veri, text alanı 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 girdiğini söyler. Bu genellikle tek başına p75 değerinden daha kullanışlıdır. %61 good oranına sahip 2450ms'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'de, masaüstü 1800ms'de. Toplam değer 2500ms gösterecekti ve "harika değil, ama çok da kötü değil" diye düşünecektiniz. Gruplandırılmış görünüm gerçek hikayeyi gösteriyor: masaüstü iyi, mobilde ç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 eğilim tespiti ile zaman içinde gruplandırılmış metrik değerlerini döndürür. Bu, "LCP'm kötüleşti mi?" ve "bu dağıtım gerilemeyi düzeltti mi?" için kullandığınız araçtır.

Parametreler

Örnek: son 7 gün içindeki LCP eğilimi

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. Eğilim değerleri improving (%5'ten daha iyi), stable (%5 içinde) veya regressing'dir (%5'ten daha kötü). Zaman serisi uç noktasını (endpoint) otomatik izleme için yararlı kılan şey budur: işlerin kötüye gidip gitmediğini öğrenmek 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'ten farklı olarak, 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ı, o aralıktaki tahmini sayfa yüklemelerinin count sayısı ve grubun Core Web Vitals eşiklerine göre nerede durduğuna bağlı bir rating değeri vardır. Açık uçlu kuyruk olduğu için son grupta to: null bulunur.

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 faydalıdır. 2400ms'lik bir p75, çoğu kullanıcının 2400ms civarında olduğu anlamına gelebilir veya %60'ının 1000ms'nin altında olduğu ve yavaş bir mobil trafik yığınının kuyruğu çektiği anlamına gelebilir. Histogram size hangisi olduğunu söyler.

Boyutlar

Bu anahtarları filters içinde veya group değeri olarak kullanın. Filtreleme, verileri belirli bir segmente daraltır. Gruplama, 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 haline geldiğini görmek için lcpel'e göre gruplayın. En kötü INP'yi üreten etkileşimleri bulmak için inpel'e göre gruplayın.

Filtre örnekleri

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

Metrikler referansı

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

API'yi bir MCP sunucusu olarak kullanma

API uç noktası, tam uyumlu bir MCP sunucusudur. Yapay zeka aracınız MCP'yi destekliyorsa (Claude Code, Cursor, Windsurf ve diğerleri), doğrudan bağlayabilirsiniz. Yapay zeka daha sonra get_metrics, get_timeseries ve get_histogram araçlarına erişebilir ve herhangi bir konuşmanın 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ı, Chrome ise "neden oluyor" kısmını sağlar.

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

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.

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

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