CoreDash API: Pobieraj dane Core Web Vitals rzeczywistych użytkowników

Twoje dane o wydajności, gdziekolwiek ich potrzebujesz

CoreDash zbiera Core Web Vitals od rzeczywistych użytkowników odwiedzających Twoją witrynę. API daje Ci dostęp do tych samych danych z dowolnego narzędzia, skryptu lub agenta AI. Trzy narzędzia, JSON na wejściu, JSON na wyjściu.

Najciekawszy przypadek użycia: podłączenie Twojego AI. CoreDash API używa tego samego protokołu co Model Context Protocol (MCP), co oznacza, że narzędzia AI, takie jak Claude, Cursor i Windsurf, mogą bezpośrednio odpytywać dane Twoich rzeczywistych użytkowników. Zapytaj swoje AI "dlaczego moje LCP jest wolne na urządzeniach mobilnych?", a ono pobierze rzeczywiste dane z pola, aby odpowiedzieć.

Na tej podstawie zbudowaliśmy CWV Superpowers. Jest to agent AI, który łączy Twoje dane z pola CoreDash z Chrome DevTools w celu diagnozowania i naprawiania problemów z Core Web Vitals. To właśnie API czyni to możliwym.

Ale nie potrzebujesz agenta AI. Polecenie curl zadziała równie dobrze.

Prowadzisz agencję lub zarządzasz wieloma projektami z jednego konta? Istnieje oddzielne Agency API, które używa klucza głównego do tworzenia, aktualizowania i usuwania projektów, a także do pobierania danych ze wszystkich z nich za pomocą jednego klucza. Reszta tej strony dotyczy API danych dla pojedynczego projektu.

Uwierzytelnianie

Każde żądanie wymaga klucza API w nagłówku Authorization:

Authorization: Bearer cdk_YOUR_API_KEY

Aby uzyskać klucz:

1. Zaloguj się na app.coredash.app
2. Przejdź do swojego projektu, następnie AI Insights, a potem Connect Your AI
3. Kliknij Create API Key i skopiuj go. Jest on wyświetlany tylko raz.

Klucze zaczynają się od cdk_ i są ograniczone do pojedynczego projektu. Możesz utworzyć wiele kluczy i unieważniać je na tej samej stronie.

Format żądania

API używa JSON-RPC 2.0. Każde żądanie to POST na adres:

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

Ciało żądania wygląda następująco:

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

Pole id może być dowolną liczbą lub ciągiem znaków. Zostanie ono odesłane w odpowiedzi. Dostępne są trzy narzędzia: get_metrics, get_timeseries oraz get_histogram.

get_metrics: obecna wydajność

Zwraca bieżące wartości Core Web Vitals z ocenami good/improve/poor. To jest narzędzie, którego używasz do pytań typu "jakie jest teraz moje LCP?".

Parametry

Przykład: pobierz wszystkie metryki

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

Surowa odpowiedź to opakowanie JSON-RPC:

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

Rzeczywiste dane to ciąg JSON wewnątrz pola text. Po sparsowaniu wyglądają one tak:

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

Obiekt distribution mówi, jaki procent rzeczywistych ładowań strony przypada na poszczególne oceny. Jest to często bardziej przydatne niż sama wartość p75. LCP na poziomie 2450ms z 61% dobrych (good) wyników oznacza, że większość użytkowników ma dobre doświadczenia, ale "ogon" (ang. tail) obniża wartość p75.

Przykład: porównanie LCP mobile vs desktop

Użyj parametru group, aby podzielić wyniki według dowolnego wymiaru. W ten sposób dowiesz się, czy Twój problem z LCP dotyczy urządzeń mobilnych:

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

Odpowiedź po sparsowaniu:

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

Mobile przy 3200ms, desktop przy 1800ms. Zagregowana wartość pokazałaby 2500ms i pomyślałbyś "nie świetnie, ale też nie tragicznie". Widok zgrupowany pokazuje prawdziwą historię: desktop jest w porządku, mobile wymaga poprawy.

Przykład: filtruj do konkretnej strony na urządzeniach mobilnych

Połącz filters, aby zawęzić wyniki dokładnie do tego ruchu, na którym Ci zależy:

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: wydajność w czasie

Zwraca wartości metryk pogrupowane w czasie (ang. bucketed) z automatycznym wykrywaniem trendów. To narzędzie jest przydatne przy pytaniach "czy moje LCP się pogorszyło?" i "czy to wdrożenie naprawiło regresję?".

Parametry

Przykład: trend LCP z ostatnich 7 dni

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

Odpowiedź po sparsowaniu:

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

Sekcja summary porównuje drugą połowę okresu z pierwszą. Wartości trendu to improving (poprawa o ponad 5%), stable (w granicach 5%) lub regressing (pogorszenie o ponad 5%). Właśnie to sprawia, że endpoint timeseries jest użyteczny do zautomatyzowanego monitorowania: nie musisz sam parsować punktów danych, aby wiedzieć, czy sytuacja się pogarsza.

get_histogram: kształt dystrybucji

Zwraca dystrybucję pojedynczej metryki jako ~40 przedziałów (bucketów) z liczbą wystąpień dla każdego zakresu. To narzędzie przydaje się, gdy wartość p75 wygląda w porządku, ale podejrzewasz obecność "długiego ogona", lub gdy chcesz zobaczyć pełen kształt swoich danych o wydajności.

Parametry

Uwaga: w przeciwieństwie do get_metrics, to narzędzie przyjmuje pojedynczy metric (nie metrics). Jedna metryka na żądanie.

Przykład: dystrybucja LCP na urządzeniach mobilnych

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

Odpowiedź po sparsowaniu:

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

Każdy przedział ma granice from/to, szacunkową liczbę załadowań strony count w tym zakresie oraz ocenę rating bazującą na tym, gdzie przedział znajduje się względem progów Core Web Vitals. Ostatni przedział ma to: null, ponieważ jest to otwarty ogon.

Szerokości przedziałów są stałe dla każdej metryki: LCP używa 250ms, INP używa 25ms, CLS używa 0.025, FCP używa 200ms, TTFB używa 125ms.

Jest to przydatne do zrozumienia kształtu Twoich danych. p75 wynoszące 2400ms może oznaczać, że większość użytkowników ma wynik w okolicach 2400ms, albo że 60% ma wynik poniżej 1000ms, a porcja wolnego ruchu mobilnego ciągnie ogon w dół. Histogram pokaże Ci, która opcja jest prawdziwa.

Wymiary

Użyj tych kluczy w filters lub jako wartość group. Filtrowanie zawęża dane do konkretnego segmentu. Grupowanie dzieli wyniki, dzięki czemu możesz porównać segmenty obok siebie.

Ogólne

Urządzenie i sieć

Atrybucja metryk

Te wymiary informują Cię, co spowodowało daną wartość metryki. Pogrupuj według lcpel, aby sprawdzić, które elementy stają się LCP na Twoich stronach. Pogrupuj według inpel, aby znaleźć interakcje generujące najgorsze INP.

Przykłady filtrów

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

Odniesienie do metryk

Domyślnym percentylem jest p75. To właśnie jego Google używa w rankingu Core Web Vitals. Jeśli 75% ładowań Twojej strony jest poniżej progu, zaliczasz test.

Używanie API jako serwera MCP

Punkt dostępowy (endpoint) API jest w pełni kompatybilnym serwerem MCP. Jeśli Twoje narzędzie AI obsługuje MCP (Claude Code, Cursor, Windsurf i inne), możesz je bezpośrednio podłączyć. AI zyska wtedy dostęp do get_metrics, get_timeseries i get_histogram jako narzędzi i będzie mogło odpytywać Twoje dane z pola jako część dowolnej konwersacji.

Tak właśnie działa CWV Superpowers: łączy się z CoreDash przez MCP, pobiera dane Twoich rzeczywistych użytkowników, otwiera Twoją stronę w Chrome i śledzi dokładną przyczynę wolnej metryki. API dostarcza część "co dzieje się na produkcji", natomiast Chrome zapewnia część "dlaczego tak się dzieje".

Możesz również podłączyć serwer MCP do własnego środowiska AI. Skieruj swojego klienta MCP na https://app.coredash.app/api/mcp za pomocą Twojego klucza API, a Twoje AI będzie mogło odpowiadać na pytania takie jak "które strony mają najgorsze INP na urządzeniach mobilnych?" używając rzeczywistych danych z pola zamiast zgadywania.

Limity zapytań

Limity dotyczą projektu na dzień i są resetowane o północy czasu UTC.

150 żądań w planie testowym (trial) to aż nadto do ręcznej eksploracji i debugowania wspieranego przez AI. Jeśli uruchamiasz zautomatyzowane monitorowanie w CI, płatne plany zapewniają 500 żądań dziennie.

Obsługa błędów

Błędy wracają jako obiekty błędu JSON-RPC:

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

Jeśli otrzymasz błąd -32001, sprawdź, czy Twój klucz zaczyna się od cdk_ i czy go nie unieważniłeś. Jeśli otrzymasz -32002, osiągnąłeś swój dzienny limit. Poczekaj na reset o północy czasu UTC lub ulepsz swój plan.