--- title: "Limity zapytań" source: https://docs.senuto.com/rate-limits api: GET /api/users/getLimits --- # 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`](#podgląd-limitów-przez-api) (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`](#podgląd-limitów-przez-api). - **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](#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`](#podgląd-limitów-przez-api) 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](/types/errors)); 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](/types/pagination)). > **Informacja:** > Dokładne wartości limitów dla Twojego planu sprawdzisz w aplikacji: **Powiadomienia → zakładka „Limity"** — pokazuje m.in. limit zapytań, liczbę fraz w raportach, projekty w Monitoringu oraz pozostałe zapytania Bazy słów kluczowych ([panel Senuto](https://app.senuto.com)). ## 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. | Moduł | Co zwiększa licznik | Podgląd per‑domena | Sygnał po przekroczeniu | | ------------------------ | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------- | | **Analiza widoczności** | Zapytanie o **nową domenę** (unikalna kombinacja `domain` + `fetch_mode` + kraj); raporty i narzędzia | `checkQuery` / `consumeLimit` _(bez osobnej strony)_ | `418` | | **Baza słów kluczowych** | Uruchomienie **nowej analizy** frazy/domeny (`getKeywords`, `getRelated`, `getQuestions`, `getStatistics`…) | — | `418` z `You have reached daily limit of queries. Daily limit value is N` | | **Monitoring** | Ręczne **odświeżenie** pozycji fraz w projekcie (licznik dobowy, na wielu pakietach bez limitu) | — | `418` | | **Analiza SERP** | Uruchomienie **nowej analizy SERP** (nowa fraza + kraj) oraz każdy `refresh` | — | `418` | | **Backlinki** | Zapytanie o dane linków dla **nowej domeny** | `checkQuery` / `consumeLimit` _(bez osobnej strony)_ | `418` | | **Narzędzia (wspólne)** | Uruchomienie narzędzia w dowolnym module (naliczane per zestaw parametrów) | — | `418` | 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](#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. | Moduł / licznik | Klucz naliczenia (co musi się zgadzać, by ponowienie było darmowe) | Grace Window | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | **Analiza widoczności** (`visibility_analysis_queries_per_day`) | `fetch_mode` + znormalizowana domena + `country_id` | 24 h od naliczenia | | **Baza słów kluczowych** (`keywords_analysis_queries_per_day`) | znormalizowane wejście (fraza/domena) + tryb danych + `country_id` | 24 h od naliczenia | | **Backlinki** (`backlinks_queries`) | znormalizowana domena + `country_id` | 24 h od naliczenia | | **Narzędzia** (`tools_daily_limit`) | pełny zestaw parametrów wywołania narzędzia (np. dla statystyk fraz KA: `country_id`, `keywords`, tryb danych) | 24 h od naliczenia | | **Analiza SERP** (`serp_analysis_daily_limit`) | brak Grace Window w liczniku — ale `create` zwraca **istniejące** zadanie dla tej samej frazy i kraju, wtedy nic nie nalicza | bezterminowo (dopóki zadanie istnieje na koncie) | | **Monitoring** (`monitoring_daily_keywords_refreshes`) | brak — każde odświeżenie zwiększa licznik | — | 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`](#podgląd-limitów-przez-api); 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](/exports-and-tasks#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](https://www.senuto.com/pl/cennik/) (stan na 2026-08-02): | Limit | Lite | Basic | Advanced | Prime | | ----------------------------- | ------- | -------- | ---------- | ---------- | | Analiza widoczności | 100 | 200 | 400 | 30 000 | | Analiza linków (Backlinki) | 100 | 400 | 2 000 | 30 000 | | Baza słów kluczowych | 50 | 100 | 200 | 30 000 | | Narzędzia (wspólna pula) | 10 | 25 | 50 | 3 000 | | Analiza SERP | 200¹ | 200¹ | 200¹ | 6 000 | | Monitoring — projekty / frazy | 5 / 150 | 10 / 300 | 20 / 1 000 | 50 / 5 000 | | Wiersze w raporcie | 500 | 5 000 | 20 000 | 150 000 | ¹ 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. > **Ostrzeżenie:** > **Tabela wyżej to zestawienie handlowe, a nie kontrakt API.** Cennik prezentuje pule w ujęciu > **miesięcznym** — i tak też działają liczniki na aktualnych pakietach, ale miesiąc liczy się > od **daty startu pakietu**, nie od pierwszego dnia kalendarzowego. Nazwy kluczy (`*_queries_per_day`, > `*_daily_limit`) są przy tym mylące: sufiks został po starszych, dobowych planach. W razie rozbieżności > obowiązuje to, co zwróci `getLimits` dla Twojego konta — z `hours_to_reset` jako źródłem prawdy > o momencie resetu. 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`](#podgląd-limitów-przez-api) 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](https://www.senuto.com/pl/cennik/); szczegóły dla większych wolumenów ustala opiekun klienta. > **Informacja:** > W kodzie integracji **nie zaszywaj wartości limitów na sztywno** — odczytaj je z `getLimits` przy starcie > i reaguj na `usage`/`hours_to_reset`. Konto może dostać więcej jednostek w dowolnym momencie. ## 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. **`GET /api/users/getLimits`** Przykładowe żądanie: ```json {} ``` Przykładowa odpowiedź: ```json { "success": true, "data": { "visibility_analysis_queries_per_day": { "limit": 25, "usage": 8, "extra_limit": 0, "hours_to_reset": 673 }, "keywords_analysis_queries_per_day": { "limit": 1000, "usage": 21, "extra_limit": 0, "hours_to_reset": 673 }, "tools_daily_limit": { "limit": 225, "usage": 6, "extra_limit": 0, "hours_to_reset": 673 }, "backlinks_queries": { "limit": 400, "usage": 0, "extra_limit": 0, "hours_to_reset": 673 }, "monitoring_daily_keywords_refreshes": { "limit": -1, "usage": 0, "extra_limit": 0, "hours_to_reset": 1 }, "monitored_keywords": { "limit": 300, "usage": 752, "extra_limit": 0, "hours_to_reset": null }, "projects": { "limit": 10, "usage": 6, "extra_limit": 0, "hours_to_reset": null } } } ``` 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](/exports-and-tasks)). - **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](#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". > **Błąd:** > `418` **nie jest** dedykowanym kodem rate‑limitu — w tym API sygnalizuje też błędy walidacji i autoryzacji. Nie zakładaj, że każde `418` to wyczerpany limit; zajrzyj do treści błędu (patrz [Błędy](/types/errors)) i — gdzie to możliwe — potwierdź stan przez `getLimits`. ## 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](/types/pagination)). - **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](#ponowienia-i-grace-window)). - **Nie zakładaj resetu o północy** — planując harmonogram integracji, odczytuj `hours_to_reset`. ## Powiązane strony - [Autoryzacja](/authorization) — token Bearer i błędy autoryzacji. - [Błędy](/types/errors) — koperta błędu i znaczenie statusu `418`. - [Paginacja](/types/pagination) — `limit`/`page` i limity rozmiaru odpowiedzi.