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

Twoje dane o wydajności, gdziekolwiek ich potrzebujesz

CoreDash zbiera dane 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 mobile?", a pobierze ono rzeczywiste dane polowe, aby odpowiedzieć.

Zbudowaliśmy CWV Superpowers na tej podstawie. Jest to agent AI, który łączy dane polowe CoreDash z Chrome DevTools, aby diagnozować i naprawiać problemy z Core Web Vitals. To API to umożliwia.

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

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 pokazywany tylko raz.

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

Format żądania

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

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. Jest ono odsyłane w odpowiedzi. Dostępne są trzy narzędzia: get_metrics, get_timeseries oraz get_histogram.

get_metrics: aktualna wydajność

Zwraca aktualne wartości Core Web Vitals z ocenami good/improve/poor. To narzędzie służy do odpowiadania na pytania typu "jakie jest moje LCP w tej chwili?".

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

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

Właściwe dane to ciąg JSON wewnątrz pola 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 mówi Ci, jaki procent rzeczywistych ładowań strony przypada na każdą ocenę. Jest to często bardziej przydatne niż sama wartość p75. LCP na poziomie 2450 ms z wynikiem 61% good oznacza, że większość użytkowników ma dobre doświadczenia, ale tzw. długi ogon ciągnie w dół wynik p75.

Przykład: porównanie LCP dla mobile i 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 (mobile):

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 to 3200 ms, desktop to 1800 ms. Zagregowany wynik pokazałby 2500 ms, a Ty pomyślałbyś: "nie jest świetnie, ale nie jest tragicznie". Widok grupowany ukazuje prawdziwą historię: desktop jest w porządku, mobile wymaga pracy.

Przykład: filtruj do określonej strony na urządzeniach mobilnych

Połącz parametry 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 podzielone na przedziały czasowe (buckety) z automatycznym wykrywaniem trendów. Tego narzędzia używasz do odpowiedzi na pytania typu "czy moje LCP się pogorszyło?" oraz "czy to wdrożenie naprawiło regresję?".

Parametry

Przykład: trend LCP w ciągu 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ą połową. Wartości trendu to improving (ponad 5% lepiej), stable (w granicach 5%) lub regressing (ponad 5% gorzej). To właśnie sprawia, że endpoint szeregów czasowych (timeseries) jest przydatny do zautomatyzowanego monitorowania: nie musisz samodzielnie analizować punktów danych, aby wiedzieć, czy sytuacja się pogarsza.

get_histogram: kształt rozkładu

Zwraca rozkład pojedynczej metryki w postaci ~40 przedziałów (bucketów) z licznikami na każdy zakres. Używasz tego narzędzia, gdy wynik p75 wygląda w porządku, ale podejrzewasz obecność długiego ogona, lub gdy chcesz zobaczyć pełny kształt swoich danych o wydajności.

Parametry

Uwaga: w przeciwieństwie do get_metrics, to żądanie przyjmuje pojedynczy parametr metric (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 przedział (bucket) ma granice from/to, count jako szacunkową liczbę załadowań strony w tym zakresie oraz rating w oparciu o to, jak przedział pozycjonuje się względem progów Core Web Vitals. Ostatni przedział ma wartość to: null, ponieważ jest to otwarty ogon (open-ended tail).

Szerokości przedziałów są stałe dla poszczególnych metryk: 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.

Jest to przydatne do zrozumienia kształtu Twoich danych. Wynik p75 równy 2400 ms może oznaczać, że większość użytkowników osiąga około 2400 ms, lub może to oznaczać, że 60% ma wynik poniżej 1000 ms, a spora część wolnego ruchu mobilnego ciągnie ogon wyników w dół. Histogram pokaże Ci, która opcja jest prawdziwa.

Wymiary

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

Ogólne

Urządzenie i sieć

Atrybucja metryk

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

Przykłady filtrów

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

Zestawienie metryk

Domyślnym percentylem jest p75. Tego właśnie używa Google w rankingu Core Web Vitals. Jeśli 75% załadowań Twojej strony mieści się poniżej progu, zdajesz test.

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 podłączyć je bezpośrednio. AI ma wtedy dostęp do narzędzi takich jak get_metrics, get_timeseries oraz get_histogram i może odpytywać Twoje dane polowe (field data) jako część dowolnej konwersacji.

Tak właśnie działa CWV Superpowers: łączy się z CoreDash przez MCP, pobiera dane od rzeczywistych użytkowników, otwiera Twoją witrynę w Chrome i śledzi dokładną przyczynę wolnej metryki. API odpowiada na pytanie "co dzieje się na produkcji", a Chrome na pytanie "dlaczego to się dzieje".

Możesz także podłączyć serwer MCP do własnego środowiska AI. Skieruj swojego klienta MCP na adres https://app.coredash.app/api/mcp używając swojego klucza API, a Twoje AI będzie w stanie odpowiedzieć na pytania typu "które strony mają najgorsze INP na urządzeniach mobilnych?" używając rzeczywistych danych polowych zamiast zgadywania.

Limity zapytań

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

150 żądań w planie Trial w zupełności wystarcza do ręcznej eksploracji i debugowania wspomaganego przez AI. Jeśli uruchamiasz automatyczne 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 nie został unieważniony. Jeśli otrzymasz błąd -32002, oznacza to, że osiągnąłeś dzienny limit. Poczekaj na reset o północy UTC lub ulepsz swój plan.