Czy API kosztuje dodatkowo?

Nie. Jest w każdym planie i w trialu, bez dopłaty i bez osobnych jednostek do wykupienia. Dane pomiarowe, które o Tobie zbieramy, są Twoje — pobranie ich nie jest usługą, za którą wypada brać drugi raz.

Czy przez API mogę zmieniać prompty albo ustawienia?

Nie i nie planujemy tego. API jest wyłącznie do odczytu. Klucz, który potrafi tylko czytać, jest po wycieku dużo mniej groźny niż taki, który potrafi też pisać.

Co zwraca API, gdy silnik danego dnia nie odpowiedział?

Wartość null i mniejszą próbę, nigdy zera. Nieudane wywołanie silnika jest wykluczone z licznika i mianownika, więc procent widoczności nie spada z powodu naszej awarii. Wielkość próby jest w odpowiedzi, żeby dało się ją sprawdzić.

Czy klucz daje dostęp do wszystkich marek w organizacji?

Tak — klucz jest wydawany dla organizacji, a parametr brand_id wybiera markę. Identyfikator marki spoza organizacji kończy się błędem 404, a nie cichym podstawieniem innej marki. Klucz może wydać wyłącznie właściciel lub członek zespołu; rola „klient (podgląd)” nie może, bo obeszłaby w ten sposób ograniczenia, które ma z założenia.

Dokumentacja

API do Twoich danych o widoczności w AI

Mierzymy, jak asystenci AI mówią o Twojej marce. To API oddaje te pomiary w surowej postaci — do hurtowni, do arkusza, do n8n, do własnego wykresu. Tylko odczyt, wyłącznie dane Twojej organizacji.

Dane, które o Tobie zbieramy, są Twoje. Dlatego API jest dostępne na każdym planie i w trialu, tak samo jak eksport plików — nie mamy zamiaru trzymać nikogo przy sobie utrudnianiem wyjścia.

Start

Pierwsze wywołanie w trzy kroki

Nic tu nie trzeba instalować. Wystarczy klucz i jeden nagłówek.

1. Wygeneruj klucz w Ustawieniach → Klucze API. Zobaczysz go tylko raz.
2. Wywołaj GET /api/v1, żeby zobaczyć listę zasobów, ich kolumny i parametry — ta sama lista jest niżej na tej stronie.
3. Pobierz dane. Każdy zasób odpowiada tą samą kopertą: meta z opisem zapytania i data z wierszami.

curl -H "Authorization: Bearer $SUPERRANK_API_KEY" \
  "https://superrank.pl/api/v1/visibility?range_days=30"

Odpowiedź ma zawsze ten sam kształt — nauka jednego wzorca wystarcza na wszystkie zasoby:

{
  "meta": {
    "dataset": "visibility",
    "brand": { "id": "...", "name": "Mevro", "domain": "mevro.app" },
    "range_days": 30,
    "engines": null,
    "generated_at": "2026-09-01T05:12:44.000Z",
    "row_count": 4,
    "columns": ["engine", "visibility_pct", "avg_position", "..."]
  },
  "data": [
    { "engine": "chatgpt", "visibility_pct": 42.1, "avg_position": 2.4 },
    { "engine": "gemini",  "visibility_pct": null, "avg_position": null }
  ]
}

Wartość null znaczy „nie zmierzyliśmy”, a nie „zero”. Silnik, który danego dnia nie odpowiedział, jest wykluczony z licznika i mianownika, a nie policzony jako brak wzmianki. Ta sama zasada obowiązuje w całym produkcie i w plikach eksportu.

Uwierzytelnienie

Klucz w nagłówku

Klucz reprezentuje całą organizację i daje dostęp do wszystkich jej danych pomiarowych. Traktuj go jak hasło do bazy.

Authorization: Bearer sr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
# albo, dla konektorow bez pola na naglowek autoryzacji:
X-Api-Key: sr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Klucz pokazujemy jeden raz, w chwili wygenerowania. U nas leży wyłącznie jego skrót SHA-256, więc zgubionego klucza nie odzyskamy — unieważnia się go i generuje nowy.
• API jest w całości tylko do odczytu. Nie ma metod zapisu i nie będzie: „zero uwięzienia danych” znaczy „zabierz swoje dane”, a nie „steruj kontem bez logowania”.
• Klucza nie przyjmujemy w adresie URL. Parametry zapytania trafiają do logów serwerów pośredniczących i do historii przeglądarki — sekret zapisany w dwóch miejscach naraz przestaje być sekretem.
• Nie wystawiamy nagłówków CORS, świadomie. To API do wywołań serwer–serwer; wołanie go z kodu strony oznaczałoby opublikowanie klucza.

Zasoby

Co możesz pobrać

Każdy zasób to jedno wywołanie GET. Nazwy kolumn są identyczne jak w eksporcie plików, więc skrypt napisany pod CSV działa na JSON-ie bez zmian.

GET /api/v1/brands

Marki własne organizacji wraz z liczbą aktywnych promptów. Punkt wyjścia: stąd bierze się brand_id do pozostałych zasobów.

Kolumny

id · name · domain · is_primary · prompt_count

GET /api/v1/visibility

Widoczność marki w podziale na silniki: procent odpowiedzi ze wzmianką, średnia pozycja i wielkość próby. Wartość null znaczy „brak danych”, nigdy zero.

Kolumny

engine · visibility_pct · avg_position · responses_analysed · responses_mentioned · sample_tier

Parametry

range_days7 | 30 | 90 — Okno danych w dniach, liczone wstecz od dzisiejszego dnia warszawskiego. Domyślnie 30.
enginechatgpt | perplexity | aio | gemini | claude — Filtr silnika; parametr można powtórzyć. Pominięty = wszystkie silniki, które mierzymy dla tej marki.
brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.

GET /api/v1/prompts

Prompty monitorowane dla marki, ze statusem i źródłem pochodzenia.

Kolumny

id · text · language · country · tags · status · source · created_at · text_updated_at

Parametry

brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.
limit — Liczba wierszy, 1–1000. Domyślnie 200.
offset — Przesunięcie okna wyników. Domyślnie 0.

GET /api/v1/responses

Surowe odpowiedzi silników z zapisanym tekstem — to jest ten zasób, o który pyta dział danych.

Kolumny

run_date · prompt_id · prompt_text · engine · status · model_version · answer_language · latency_ms · input_tokens · output_tokens · text

Parametry

range_days7 | 30 | 90 — Okno danych w dniach, liczone wstecz od dzisiejszego dnia warszawskiego. Domyślnie 30.
enginechatgpt | perplexity | aio | gemini | claude — Filtr silnika; parametr można powtórzyć. Pominięty = wszystkie silniki, które mierzymy dla tej marki.
brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.
limit — Liczba wierszy, 1–1000. Domyślnie 200.
offset — Przesunięcie okna wyników. Domyślnie 0.

GET /api/v1/mentions

Wzmianki marek w odpowiedziach: offsety w tekście, sentyment i sposób wykrycia.

Kolumny

run_date · prompt_id · prompt_text · engine · response_id · brand · is_self · span_start · span_end · sentiment_label · sentiment_score · detection

Parametry

range_days7 | 30 | 90 — Okno danych w dniach, liczone wstecz od dzisiejszego dnia warszawskiego. Domyślnie 30.
enginechatgpt | perplexity | aio | gemini | claude — Filtr silnika; parametr można powtórzyć. Pominięty = wszystkie silniki, które mierzymy dla tej marki.
brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.
limit — Liczba wierszy, 1–1000. Domyślnie 200.
offset — Przesunięcie okna wyników. Domyślnie 0.

GET /api/v1/citations

Adresy cytowane przez silniki, z kategorią źródła i informacją, czy to domena marki.

Kolumny

run_date · prompt_id · prompt_text · engine · response_id · url · domain · is_pl_source · source_category · own_domain

Parametry

range_days7 | 30 | 90 — Okno danych w dniach, liczone wstecz od dzisiejszego dnia warszawskiego. Domyślnie 30.
enginechatgpt | perplexity | aio | gemini | claude — Filtr silnika; parametr można powtórzyć. Pominięty = wszystkie silniki, które mierzymy dla tej marki.
brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.
limit — Liczba wierszy, 1–1000. Domyślnie 200.
offset — Przesunięcie okna wyników. Domyślnie 0.

GET /api/v1/competitors

Ranking konkurentów z okna: obecność, udział głosu, średnia pozycja i próg próby.

Kolumny

rank · name · is_self · mentioned_responses · responses_total · presence_pct · sov_pct · avg_position · prompts_seen · sample_tier

Parametry

range_days7 | 30 | 90 — Okno danych w dniach, liczone wstecz od dzisiejszego dnia warszawskiego. Domyślnie 30.
enginechatgpt | perplexity | aio | gemini | claude — Filtr silnika; parametr można powtórzyć. Pominięty = wszystkie silniki, które mierzymy dla tej marki.
brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.

GET /api/v1/metrics

Metryki dzienne w ziarnie prompt × silnik × dzień przebiegu — materiał na własne wykresy.

Kolumny

day · prompt_id · prompt_text · engine · run_ok · mentioned · position · own_mentions · total_brand_slots · sentiment_avg · citations_total · own_domain_cited

Parametry

range_days7 | 30 | 90 — Okno danych w dniach, liczone wstecz od dzisiejszego dnia warszawskiego. Domyślnie 30.
enginechatgpt | perplexity | aio | gemini | claude — Filtr silnika; parametr można powtórzyć. Pominięty = wszystkie silniki, które mierzymy dla tej marki.
brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.
limit — Liczba wierszy, 1–1000. Domyślnie 200.
offset — Przesunięcie okna wyników. Domyślnie 0.

GET /api/v1/gaps

Luki: prompty, w których konkurenci są, a marki nie ma. To samo wyliczenie, co na ekranie /luki.

Kolumny

prompt_id · prompt_text · gap_responses · engines · who · last_run_date

Parametry

range_days7 | 30 | 90 — Okno danych w dniach, liczone wstecz od dzisiejszego dnia warszawskiego. Domyślnie 30.
enginechatgpt | perplexity | aio | gemini | claude — Filtr silnika; parametr można powtórzyć. Pominięty = wszystkie silniki, które mierzymy dla tej marki.
brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.

GET /api/v1/timeseries

Szereg czasowy w ziarnie dzień × silnik: widoczność, średnia pozycja, udział głosu, sentyment, cytowania i luki — każdy wiersz z datą. Z tego zasobu czyta konektor Looker Studio; pozostałe zasoby są eksportem, nie osią czasu.

Kolumny

run_date · engine · prompts_measured · responses_analysed · responses_mentioned · visibility_pct · avg_position · sov_pct · sentiment_avg · citations_total · own_citations · gap_responses · sample_tier

Parametry

range_days7 | 30 | 90 — Okno danych w dniach, liczone wstecz od dzisiejszego dnia warszawskiego. Domyślnie 30.
enginechatgpt | perplexity | aio | gemini | claude — Filtr silnika; parametr można powtórzyć. Pominięty = wszystkie silniki, które mierzymy dla tej marki.
brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.

GET /api/v1/recommendations

Rekomendacje wygenerowane regułami R1–R5 wraz ze statusem prowadzenia.

Kolumny

id · type · title · body_md · impact · status · prompt_id · created_at

Parametry

brand_id — Marka własna, której dotyczy zapytanie. Pominięty = marka pierwotna organizacji. Obce id kończy się błędem 404, nie cichym podstawieniem innej marki.
limit — Liczba wierszy, 1–1000. Domyślnie 200.
offset — Przesunięcie okna wyników. Domyślnie 0.

Limity

Ile żądań dziennie

Limit jest zabezpieczeniem przed nadużyciem, nie dławikiem sprzedażowym — jest o dwa rzędy wielkości wyższy niż jakakolwiek sensowna synchronizacja danych.

Plan	Żądania na dobę
Trial	2000
Start	5000
Pro	10 000
Agencja	20 000

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9987
X-RateLimit-Reset: 2026-09-02T22:00:00.000Z
X-Api-Version: v1

Licznik żyje w bazie, a nie w pamięci pojedynczej instancji, więc pozostały limit w nagłówku jest liczbą prawdziwą, a nie szacunkiem. Zeruje się o północy czasu warszawskiego — tej samej, którą produkt nazywa dniem pomiaru.

Błędy

Co może pójść nie tak

Każdy błąd ma stabilny kod i zdanie po polsku. Powody nie są sklejane w jedno „brak dostępu”, bo po drugiej stronie oznaczają różne rzeczy do zrobienia.

Kod	HTTP	Znaczenie
brak_klucza	401	Nie było nagłówka z kluczem. Dodaj Authorization: Bearer.
nieznany_klucz	401	Klucz nie pasuje do żadnego wydanego. Sprawdź, czy nie skopiował się ze spacją.
klucz_uniewazniony	403	Klucz istniał, ale został unieważniony. Wygeneruj nowy — starego nie da się przywrócić.
limit_wyczerpany	429	Dzienny limit żądań skończył się. Nagłówek Retry-After podaje, ile sekund zostało do zerowania licznika.
nieznany_zasob	404	Taki zasób nie istnieje. Lista dostępnych jest pod GET /api/v1.
brak_marki	404	Podane brand_id nie należy do tej organizacji albo organizacja nie ma jeszcze marki. Nie podstawiamy w takim wypadku innej marki — cicha podmiana danych byłaby gorsza niż błąd.
zla_metoda	405	Użyto metody innej niż GET. API jest tylko do odczytu.
api_niedostepne	503	API nie jest w tej chwili skonfigurowane po naszej stronie. To błąd u nas, nie u Ciebie.

Looker Studio

Konektor do Looker Studio

Agencja, która ma już własny szablon raportu w Lookerze, nie musi go porzucać. Konektor podaje tam dane z Twojego konta: jeden wiersz na dzień i silnik, z datą — więc wykres czasowy rysuje się sam.

Looker Studio przyjmuje dane spoza katalogu Google wyłącznie przez konektor w Apps Script. Kod konektora jest gotowy i otwarty (katalog integracje/looker w repozytorium); po stronie Google zostaje wklejenie go do projektu i wdrożenie.

1. Wygeneruj klucz API w Ustawieniach → Klucze API i skopiuj go — pokazujemy go jeden raz.
2. Załóż projekt w Apps Script, wklej pliki konektora i wdróż go jako dodatek do Looker Studio.
3. W Looker Studio wybierz „Build your own connector”, wklej identyfikator wdrożenia i podaj klucz API.

Zakresu dat nie ustawia się w konektorze — bierze go z wykresu w Lookerze. API zna okna 7, 30 i 90 dni, więc konektor pobiera najmniejsze, które pokrywa żądanie. Zakres dłuższy niż 90 dni zwraca 90 dni: starsze dane podlegają czyszczeniu retencyjnemu.

Pola konektora

GET /api/v1/timeseries?range_days=30
X-Api-Key: sr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Puste pole to „nie zmierzyliśmy”, nigdy zero. Dzień bez udanego pomiaru rysuje się jako przerwa w serii, a nie jako spadek do zera.
• Widoczność, udział głosu, średnia pozycja i sentyment mają ziarno dnia i silnika i nie sumują się — średnia ze średnich nie jest średnią. Do grubszych okresów służą liczniki: odpowiedzi ze wzmianką podzielone przez odpowiedzi w próbie.
• Zakres konektora to zakres klucza: tylko odczyt i tylko dane Twojej organizacji. To API nie ma metody innej niż GET.

Konektor nie jest dziś opublikowany w publicznej galerii konektorów Google — publikacja to osobny przegląd po ich stronie. Bez niej działa tak samo, tylko instaluje się z linku wdrożenia. Instrukcja krok po kroku leży w README konektora.

MCP

Pytaj o widoczność w Claude albo Cursorze

Serwer MCP podłącza te same zasoby do asystenta, którego już używasz — nie musisz przepisywać danych do czatu ani budować własnego panelu. Uwierzytelnia się tym samym kluczem.

{
  "mcpServers": {
    "superrank": {
      "command": "node",
      "args": ["/sciezka/do/superrank-mcp/dist/server.js"],
      "env": { "SUPERRANK_API_KEY": "sr_live_..." }
    }
  }
}

Narzędzia: raport widoczności marki, lista promptów, cytowane źródła, luki wobec konkurencji i rekomendacje. Każde woła dokładnie ten sam zasób API, co skrypt — asystent nie ma osobnej, gorszej ścieżki do danych.

Serwer jest dziś dystrybuowany jako kod źródłowy, a nie jako paczka w npm — publikacja pakietu czeka na pierwsze wdrożenia u klientów. Napisz na pomoc@superrank.pl, a odeślemy archiwum z gotowym „dist/” i tę samą konfigurację, co powyżej.

Pliki

Eksport w JSON, XLSX i CSV

Jednorazowe pobranie nie wymaga klucza — wystarczy być zalogowanym. Ta sama ścieżka i te same kolumny, wybór formatu jednym parametrem.

GET /raporty/eksport?rodzaj=citations&zakres=30&format=json
GET /raporty/eksport?rodzaj=citations&zakres=30&format=xlsx
GET /raporty/eksport?rodzaj=citations&zakres=30&format=csv&sep=;

CSV zapisujemy z BOM-em i średnikiem, żeby polski Excel otworzył go dwuklikiem bez rozjeżdżania kolumn. JSON zachowuje typy: null zostaje nullem, fałsz zostaje fałszem. XLSX to gotowy arkusz z zamrożonym nagłówkiem. Eksport działa na każdym planie i w trialu — nigdy go nie blokujemy.

Pytania

Najczęstsze wątpliwości

Cztery rzeczy, o które pytają integratorzy, zanim napiszą pierwszą linię kodu.

Czy API kosztuje dodatkowo?: Nie. Jest w każdym planie i w trialu, bez dopłaty i bez osobnych jednostek do wykupienia. Dane pomiarowe, które o Tobie zbieramy, są Twoje — pobranie ich nie jest usługą, za którą wypada brać drugi raz.
Czy przez API mogę zmieniać prompty albo ustawienia?: Nie i nie planujemy tego. API jest wyłącznie do odczytu. Klucz, który potrafi tylko czytać, jest po wycieku dużo mniej groźny niż taki, który potrafi też pisać.
Co zwraca API, gdy silnik danego dnia nie odpowiedział?: Wartość null i mniejszą próbę, nigdy zera. Nieudane wywołanie silnika jest wykluczone z licznika i mianownika, więc procent widoczności nie spada z powodu naszej awarii. Wielkość próby jest w odpowiedzi, żeby dało się ją sprawdzić.
Czy klucz daje dostęp do wszystkich marek w organizacji?: Tak — klucz jest wydawany dla organizacji, a parametr brand_id wybiera markę. Identyfikator marki spoza organizacji kończy się błędem 404, a nie cichym podstawieniem innej marki. Klucz może wydać wyłącznie właściciel lub członek zespołu; rola „klient (podgląd)” nie może, bo obeszłaby w ten sposób ograniczenia, które ma z założenia.

Klucz wygenerujesz w ustawieniach organizacji: Ustawienia → Klucze API