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

Twoje dane o wydajności wszędzie tam, gdzie ich potrzebujesz

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

Najciekawszy przypadek użycia: podłączenie AI. API CoreDash korzysta z tego samego protokołu co Model Context Protocol (MCP). Dzięki temu narzędzia AI, takie jak Claude, Cursor i Windsurf, mogą bezpośrednio pobierać dane Twoich rzeczywistych użytkowników. Zapytaj swoje AI: „dlaczego mój LCP jest wolny na urządzeniach mobilnych?”, a pobierze ono rzeczywiste field data, by odpowiedzieć.

Na tej bazie zbudowaliśmy CWV Superpowers. To agent AI, który łączy field data z CoreDash z Chrome DevTools, aby diagnozować i naprawiać problemy z Core Web Vitals. To właśnie API umożliwia jego działanie.

Ale nie potrzebujesz agenta AI. Polecenie curl zadziała tak samo dobrze.

Prowadzisz agencję lub zarządzasz wieloma projektami z jednego konta? Dostępne jest osobne Agency API. Używa ono klucza głównego (master key) do tworzenia, aktualizowania i usuwania projektów oraz do pobierania danych ze wszystkich projektów za pomocą jednego klucza. Dalsza część 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 do AI Insights, a potem do Connect Your AI
3. Kliknij Create API Key i skopiuj go. Jest wyświetlany tylko raz.

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

Format żądania

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

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

Treść żą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. Jest zwracane w odpowiedzi. Dostępne są trzy narzędzia: get_metrics, get_timeseries oraz get_histogram.

get_metrics: bieżąca wydajność

Zwraca bieżące wartości Core Web Vitals wraz z ocenami good/improve/poor. To narzędzie służy do odpowiadania na pytania typu „jaki jest mój LCP w tej chwili?”.

Parametry

Przykład: pobranie wszystkich metryk

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 obiekt JSON-RPC:

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

Właściwe dane to ciąg znaków JSON w polu text. Po sparsowaniu wygląda to 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 informuje, jaki procent rzeczywistych załadowań strony odpowiada poszczególnym ocenom. Często jest to bardziej przydatne niż sama wartość p75. LCP na poziomie 2450 ms przy 61% dobrych ocen (good) oznacza, że większość użytkowników ma dobre doświadczenia, ale długi ogon zaniża wynik p75.

Przykład: porównanie LCP na urządzeniach mobilnych i desktopach

Użyj parametru group, aby podzielić wyniki według dowolnego wymiaru. W ten sposób dowiesz się, czy 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"
      }
    }
  }'

Sparsowana odpowiedź:

{
  "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 na poziomie 3200 ms, desktop na poziomie 1800 ms. Dane zagregowane pokazałyby 2500 ms i pomyślisz: „nie jest świetnie, ale nie ma tragedii”. Widok pogrupowany pokazuje prawdę: desktop działa dobrze, mobile wymaga pracy.

Przykład: filtrowanie 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 wraz z automatycznym wykrywaniem trendów. To narzędzie służy do odpowiadania na pytania takie jak „czy mój LCP się pogorszył?” oraz „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"
      }
    }
  }'

Sparsowana odpowiedź:

{
  "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 (ponad 5% poprawy), stable (w granicach 5%) lub regressing (ponad 5% pogorszenia). Dzięki temu endpoint timeseries jest przydatny do automatycznego monitoringu – nie musisz samodzielnie analizować poszczególnych punktów danych, aby dowiedzieć się, czy sytuacja się pogarsza.

get_histogram: kształt rozkładu

Zwraca rozkład pojedynczej metryki w postaci około 40 kubełków (buckets) z liczbą wystąpień dla każdego zakresu. To narzędzie przydaje się, gdy p75 wygląda dobrze, ale podejrzewasz istnienie długiego ogona, lub gdy chcesz zobaczyć pełny kształt danych o wydajności.

Parametry

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

Przykład: rozkład 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"
      }
    }
  }'

Sparsowana odpowiedź:

{
  "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 kubełek ma granice from/to, szacowaną liczbę załadowań strony w tym zakresie (count) oraz ocenę (rating) opartą na tym, jak kubełek pozycjonuje się względem progów Core Web Vitals. Ostatni kubełek ma wartość to: null, ponieważ reprezentuje otwarty koniec ogona.

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

Pomaga to zrozumieć strukturę Twoich danych. Wynik p75 na poziomie 2400 ms może oznaczać, że większość użytkowników ma wynik w okolicach 2400 ms, ale może też oznaczać, że 60% z nich ma wynik poniżej 1000 ms, a część wolnego ruchu z komórek ciągnie ogon w dół. Histogram pozwala to sprawdzić.

Wymiary

Używaj tych kluczy w filters lub jako wartości group. Filtrowanie zawęża dane do określonego segmentu. Grupowanie dzieli wyniki, umożliwiając porównywanie segmentów obok siebie.

Ogólne

Urządzenie i sieć

Atrybucja metryk

Te wymiary wskazują, co było przyczyną danej wartości metryki. Pogrupuj według lcpel, aby zobaczyć, które elementy najczęściej wyznaczają LCP na Twoich stronach. Pogrupuj według inpel, aby znaleźć interakcje powodujące najgorsze wartości INP.

Przykłady filtrów

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

Zestawienie metryk

Domyślny percentyl to p75. Tego wskaźnika używa Google do rankingu Core Web Vitals. Jeśli 75% wczytań Twojej strony mieści się poniżej progu, test jest zaliczony.

Używanie API jako serwera MCP

Endpoint API to w pełni kompatybilny serwer MCP. Jeśli Twoje narzędzie AI obsługuje MCP (Claude Code, Cursor, Windsurf i inne), możesz je bezpośrednio podłączyć. AI uzyska wtedy dostęp do narzędzi get_metrics, get_timeseries oraz get_histogram i będzie mogło odpytywać o Twoje field data w trakcie dowolnej rozmowy.

Tak działa CWV Superpowers: łączy się z CoreDash przez MCP, pobiera dane rzeczywistych użytkowników, otwiera Twoją stronę w Chrome i wskazuje dokładną przyczynę słabego wyniku metryki. API dostarcza informacji o tym, „co dzieje się na produkcji”, a Chrome odpowiada na pytanie „dlaczego tak się dzieje”.

Możesz także podłączyć serwer MCP do własnego środowiska AI. Skieruj klienta MCP na adres https://app.coredash.app/api/mcp, podając swój klucz API. Wtedy Twoje AI będzie mogło odpowiadać na pytania typu „które strony mają najgorszy INP na urządzeniach mobilnych?”, korzystając z rzeczywistych field data zamiast zgadywać.

Limity żądań

Limity są naliczane dla projektu na dzień i resetują się o północy UTC.

150 żądań w bezpłatnym planie (trial) w zupełności wystarcza do ręcznego testowania i debugowania z pomocą AI. Jeśli uruchamiasz automatyczny monitoring w CI, płatne plany oferują 500 żądań dziennie.

Obsługa błędów

Błędy są zwracane jako obiekty błędów JSON-RPC:

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

Jeśli otrzymasz kod -32001, upewnij się, że Twój klucz zaczyna się od cdk_ i nie został unieważniony. Błąd -32002 oznacza osiągnięcie dziennego limitu. Poczekaj na reset o północy UTC lub przejdź na wyższy plan.