Limity zapytań

Każdy moduł Senuto ma limit zapytań rozliczany okresowo. Ta strona opisuje wspólny model limitów w całym systemie — zasady są takie same niezależnie od modułu, różni się tylko to, co zwiększa dany licznik i gdzie sprawdzisz jego stan.

Jak działają limity

Reguły wspólne dla wszystkich modułów:

• Licznik per moduł. Każdy moduł ma własny limit; liczniki nie sumują się między modułami (wyjątek: narzędzia współdzielą jeden — patrz niżej).
• Okres rozliczeniowy: miesięczny, liczony od daty startu pakietu. Mimo sufiksów _per_day i _daily_ w nazwach kluczy, na aktualnych pakietach liczniki zapytań resetują się raz na miesiąc, w miesięczną rocznicę uruchomienia pakietu — nie o północy i nie pierwszego dnia miesiąca. Dobowe liczniki zostały tylko na wycofanych, starszych planach. Nie zakładaj doby — czytaj hours_to_reset z GET /api/users/getLimits (typowa wartość dla świeżo odnowionego pakietu to kilkaset godzin).
• Jedna pula na konto — API i aplikacja czerpią z tego samego licznika. Sprawdzenie nowej domeny klikaniem w panelu zużywa tę samą jednostkę co odpowiadające mu wywołanie API; nie ma osobnego „limitu API” obok „limitu aplikacji”. Dlatego wartości w panelu (Powiadomienia → Limity) i te z getLimits zawsze się zgadzają, a pętla w integracji potrafi wyczerpać limit, którego potrzebujesz do pracy w interfejsie.
• Wspólny dla całego konta. Limit dotyczy konta, nie pojedynczego tokenu czy użytkownika. Ile godzin zostało do wyzerowania danego licznika, podaje pole hours_to_reset w GET /api/users/getLimits.
• Powtórzenie tego samego zapytania nie nalicza się dwa razy. Naliczenie idzie na treść zapytania (domena/fraza + kraj + tryb), a nie na żądanie — powtórka w oknie Grace Window jest darmowa. Szczegóły i wyjątki: Ponowienia i Grace Window.
• Wartość zależy od planu. Nie zakładaj sztywnych liczb w kodzie — odczytaj wszystkie limity naraz programowo przez GET /api/users/getLimits lub sprawdź w aplikacji.
• Przekroczenie → status 418. To ten sam status co dla błędów walidacji — nie jest dedykowanym kodem rate‑limitu. Rozróżniaj przyczyny po treści błędu (patrz Błędy); część modułów zwraca czytelny komunikat o limicie.
• Osobno: limity rozmiaru odpowiedzi. Niezależnie od limitu zapytań obowiązują limity liczby wierszy na raport — przeglądanie kolejnych stron wyników zwykle nie zużywa licznika zapytań (patrz Paginacja).

Limity w poszczególnych modułach

Każdy moduł liczy limit inną „jednostką” — poniżej, co dokładnie zwiększa licznik i jak rozpoznasz wyczerpanie.

Niuanse liczenia, o których warto wiedzieć:

• Per jednostka, nie per żądanie. W Analizie widoczności wielokrotne odpytanie tej samej domeny (np. pozycje, potem wzrosty i spadki dla zalando.pl) to jedna pozycja limitu. Analogicznie w innych modułach liczy się nowa jednostka pracy (nowa fraza, nowe odświeżenie, nowa analiza), a nie każde wywołanie — patrz Ponowienia i Grace Window.
• Odczyt już pobranych danych zwykle nie kosztuje. Np. w Bazie słów kluczowych paginowanie gotowych wyników (getGroups, getResults, getGroupKeywords) podlega tylko limitowi liczby wierszy, nie limitowi zapytań.
• Narzędzia współdzielą jeden licznik. Rodziny narzędzi w różnych modułach (tools/* Analizy widoczności, narzędzia Bazy słów kluczowych, Monitoringu, Analizy SERP) czerpią z jednej wspólnej puli uruchomień (tools_daily_limit) — planuj je łącznie.

Ponowienia i Grace Window

Ponowienie żądania po timeoucie zwykle nie naliczy limitu drugi raz. Licznik rośnie od treści zapytania, nie od pojedynczego żądania: kolejne pytanie o tę samą jednostkę jest darmowe w oknie zwanym Grace Window. Wyjątkiem jest Monitoring: każde odświeżenie pozycji zwiększa licznik monitoring_daily_keywords_refreshes.

API nie ma nagłówka Idempotency-Key. Przy naliczaniu od treści zapytania nie jest potrzebny.

Praktyczne wnioski:

• Timeout po stronie klienta? Powtórz to samo żądanie. Dla raportów Analizy widoczności, Bazy słów kluczowych i Backlinków ponowienie w ciągu 24 h nie zużyje drugiej jednostki, niezależnie od tego, czy pierwsze żądanie zdążyło się policzyć po stronie Senuto.
• Ponawiaj identyczny payload. Dla narzędzi klucz liczony jest z serializowanych parametrów, więc zmiana kolejności fraz w tablicy keywords albo dodanie opcjonalnego parametru tworzy nową jednostkę. Retry wysyłaj bajt w bajt tak samo jak pierwotne żądanie.
• Chcesz najpierw sprawdzić, czy operacja już się naliczyła? GET /api/users/getLimits pokaże aktualny usage, a dla pojedynczej domeny w Analizie widoczności — checkQuery. Oba są odczytowe. Nie ma natomiast rejestru pojedynczych wywołań: „czy ten konkretny request przeszedł” sprawdza się właśnie przez usage albo przez powtórzenie zapytania.
• Uważaj na refresh Analizy SERP i odświeżanie Monitoringu — te dwie operacje naliczają się za każdym razem, więc retry po timeoucie kosztuje: ustaw wysoki timeout klienta zamiast agresywnego ponawiania. Odświeżanie Monitoringu bywa przy tym darmowe w praktyce — monitoring_daily_keywords_refreshes ma na wielu pakietach limit: -1, czyli brak limitu. Sprawdź swoje konto w getLimits; to jedyny licznik, który faktycznie resetuje się co dobę.
• Zadania asynchroniczne mają własny, mocniejszy mechanizm — task_id i listę zadań konta. Patrz Eksporty i zadania async → Ponowienia po timeoucie.

Ile dokładnie wynoszą limity w moim planie?

Zakres API jest ten sam w każdym pakiecie — różnią się wysokości limitów. Orientacyjne wartości dla standardowych pakietów podaje cennik Senuto  (stan na 2026-08-02):

¹ Analiza SERP nie wchodzi w skład pakietów Lite, Basic i Advanced — 200 zapytań dostajesz po dokupieniu dodatku Analiza SERP. Bez niego endpointy /api/serp_analysis/* zwrócą błąd niezależnie od dostępu do API.

Dlatego w kodzie nie opieraj się na tabeli: wartości zależą też od dokupionych rozszerzeń (extra_limit) i indywidualnych ustaleń. Zamiast tego:

• Odczytaj swoje limity programowo — GET /api/users/getLimits zwraca komplet wartości dla Twojego konta jednym wywołaniem, bez zużywania jednostek. To jedyne źródło, które nigdy się nie zdezaktualizuje.
• W aplikacji — Powiadomienia → zakładka „Limity”.
• Przed zakupem albo przy porównywaniu pakietów — zestawienie planów znajdziesz w cenniku Senuto ; szczegóły dla większych wolumenów ustala opiekun klienta.

Podgląd limitów przez API

Stan wszystkich limitów konta zwraca jedno wywołanie GET /api/users/getLimits, niezależnie od modułu. Działa nawet bez dostępu do API i nie zużywa żadnej jednostki.

Odpowiedź to mapa klucz_limitu → { limit, usage, extra_limit, hours_to_reset } (zwykle kilkadziesiąt kluczy — wyżej fragment). Jak czytać wartości:

• limit — wartość limitu w Twoim planie. -1 oznacza brak limitu (np. monitoring_daily_keywords_refreshes powyżej). Bywa też datą (limity ważności danych).
• usage — bieżące zużycie w trwającym okresie rozliczeniowym; null dla limitów, które nie są licznikiem „zużywalnym” (np. limity rozmiaru raportu *_rows_per_report).
• extra_limit — dodatkowe jednostki ponad plan (dokupione rozszerzenia).
• hours_to_reset — ile godzin do wyzerowania licznika; null, gdy limit nie resetuje się cyklicznie. To jedyny wiarygodny sygnał okresu rozliczeniowego — wartości rzędu kilkuset godzin (jak 673 w przykładzie wyżej) to normalny cykl miesięczny, mimo _per_day w nazwie klucza.

Klucze odpowiadają modułom, np. visibility_analysis_queries_per_day, keywords_analysis_queries_per_day, serp_analysis_daily_limit, backlinks_queries, tools_daily_limit, a także limity ilościowe (monitored_keywords, projects) i rozmiarowe (*_rows_per_report).

Czy jest rate limit na sekundę/minutę?

Nie — API nie wymusza limitu żądań na sekundę ani na minutę. Nie ma statusu 429, nie ma nagłówków X-RateLimit-* ani Retry-After, a 418 sygnalizuje walidację lub wyczerpany limit okresowy, nie tempo wysyłki. Jedyną twardą granicą są liczniki zapytań opisane wyżej.

Praktyczne konsekwencje dla integracji:

• Nie zrównoleglaj agresywnie. Brak throttlingu w aplikacji nie znaczy, że warstwa brzegowa (proxy, WAF, ochrona przed nadużyciami) przepuści dowolny ruch — kilkadziesiąt równoległych połączeń z jednego IP może zostać odrzuconych zanim dotrą do API, i wtedy odpowiedź nie będzie miała koperty {success, data}.
• Sekwencyjnie z krótkim odstępem (rzędu ~1 s) to bezpieczny domyślny tryb pracy — tak działa walidacja tej dokumentacji.
• Wąskim gardłem bywa czas odpowiedzi, nie liczba żądań: szerokie raporty historyczne liczą się długo (patrz Eksporty i zadania async).
• Retry rób z backoffem i wyłącznie dla 5xx oraz timeoutów — ponawianie 418 nic nie zmieni, bo to odrzucone żądanie, a nie chwilowa awaria. Retry po timeoucie jest bezpieczny kosztowo, patrz Ponowienia i Grace Window.

Jak rozpoznać wyczerpanie limitu

• Zawczasu, programowo — GET /api/users/getLimits pokazuje usage/limit/hours_to_reset dla wszystkich modułów naraz. Jest odczytowe — nie zużywa limitu.
• W trakcie — po przekroczeniu żądanie kończy się statusem 418. Część modułów dołącza czytelny komunikat (np. Baza słów kluczowych: You have reached daily limit of queries. Daily limit value is N — komunikat mówi „daily”, ale dotyczy limitu okresu rozliczeniowego).
• W aplikacji — bieżący stan wszystkich limitów: Powiadomienia → zakładka „Limity”.

Dobre praktyki

• Sprawdzaj przed serią przez getLimits — nie zużywa limitu, a chroni przed nieoczekiwanym 418.
• Cache’uj po stronie klienta — dane raportów zmieniają się najwyżej raz dziennie; nie powtarzaj tego samego zapytania.
• Rób odstępy między żądaniami — przy większej liczbie wywołań dodaj krótkie opóźnienie (rzędu ~1 s).
• Paginuj zamiast wielkich limit — przeglądanie stron zwykle nie zużywa licznika zapytań (patrz Paginacja).
• Planuj narzędzia łącznie — wszystkie narzędzia dzielą jedną pulę.
• Retry po timeoucie wysyłaj identycznie — ten sam payload trafia w Grace Window i nie kosztuje drugiej jednostki (patrz Ponowienia i Grace Window).
• Nie zakładaj resetu o północy — planując harmonogram integracji, odczytuj hours_to_reset.

Powiązane strony

• Autoryzacja — token Bearer i błędy autoryzacji.
• Błędy — koperta błędu i znaczenie statusu 418.
• Paginacja — limit/page i limity rozmiaru odpowiedzi.