--- title: "Historia URL-i: utracone (`getLost`)" source: https://docs.senuto.com/modules/visibility_analysis/va-history-urls-getLost api: POST /api/visibility_analysis/reports/history/urls/getLost --- # Historia URL-i: utracone (`getLost`) **`POST /api/visibility_analysis/reports/history/urls/getLost`** Zwraca adresy URL domeny **utracone** w badanym okresie — takie, które przestały rankować między `date_min` a `date_max` (tryb `MODE_LOSE`). W odróżnieniu od raportu historii fraz, ten raport agreguje dane **po adresach URL**, a nie po pojedynczych frazach — każdy wiersz opisuje jeden URL wraz ze statystykami: liczbą fraz, przedziałami pozycji (`top3`/`top10`/`top50`), widocznością (szacowany ruch), średnią i sumaryczną pozycją oraz liczbą fraz, które zyskały (`wins`) i straciły (`losses`). | URL | Frazy | TOP3 | TOP3 poprz. | TOP3 Δ | TOP3 % | TOP10 | TOP10 poprz. | TOP10 Δ | TOP10 % | TOP50 | TOP50 poprz. | TOP50 Δ | TOP50 % | Widoczność | Widoczność poprz. | Widoczność Δ | Widoczność % | Śr. pozycja | Śr. pozycja poprz. | Śr. pozycja Δ | Suma pozycji | Suma pozycji poprz. | Suma pozycji Δ | Suma pozycji % | Wzrosty (fraz) | Spadki (fraz) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | zalando.pl/ochnik/ | 5 | 0 | 2 | -2 | -1 | 3 | 2 | 1 | 0.5 | 2 | 1 | 1 | 1 | 22678.5 | 79197.19 | -56518.69 | -0.7136 | 12 | 7 | 5 | 63 | 38 | 25 | 0.6579 | 0 | 5 | | zalando.pl/akcesoria-torby-kobiety/pinko/ | 1 | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 5321.25 | 8672.4 | -3351.15 | -0.3864 | 3 | 2 | 1 | 3 | 2 | 1 | 0.5 | 0 | 1 | _zalando.pl (2026-06-20 → 2026-06-29) — URL-e utracone w okresie. Wszystkie pola wiersza (poza mapami o kluczach-datach — są w JSON). Uwaga: keywords_count, wins i losses przychodzą jako stringi._ --- ## Żądanie `POST` `/api/visibility_analysis/reports/history/urls/getLost` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "date_min": "2026-06-20", "date_max": "2026-06-29", "country_id": 1, "order": { "prop": "statistics.visibility.current", "dir": "desc" } } ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "date_min": "2026-06-20", "date_max": "2026-06-29", "country_id": 1, "order": { "prop": "statistics.visibility.current", "dir": "desc" }, "limit": 2, "page": 1 } ``` **cURL** ```bash curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/history/urls/getLost' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{ "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "date_min": "2026-06-20", "date_max": "2026-06-29", "country_id": 1, "order": { "prop": "statistics.visibility.current", "dir": "desc" } }' ``` ### Parametry ```ts type HistoryUrlsGetLostRequest = { /** * **Wymagane**. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`. */ domain: string; /** * **Wymagane**. Sposób interpretacji `domain`. * - `topLevelDomain` — cała domena (najczęstszy przypadek; wartość "domain" **nie istnieje**) * - `subdomain` — pojedyncza subdomena * - `catalog` — ścieżka/katalog * - `url` — dokładny URL */ fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url'; /** * **Wymagane**. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` z komunikatem "Unknown country_id". */ country_id: number; /** * **Wymagane**. Początek zakresu dat, `YYYY-MM-DD`. Musi być nie późniejszy niż `date_max`. */ date_min: string; /** * **Wymagane**. Koniec zakresu dat, `YYYY-MM-DD`. Musi być nie wcześniejszy niż `date_min`. */ date_max: string; /** * **Wymagane**. **Pojedyncza** dyrektywa sortowania (jeden obiekt — nie tablica). * * Dozwolone wartości `prop` (tylko 4 — inaczej niż w raporcie fraz): * - `statistics.visibility.current` * - `statistics.visibility.previous` * - `statistics.visibility.diff` * - `statistics.visibility.percent` * * Inna wartość → `418` `invalid_data` z komunikatem "This value is not allow. Please use correct colum name" (pisownia oryginalna). */ order: { prop: | 'statistics.visibility.current' | 'statistics.visibility.previous' | 'statistics.visibility.diff' | 'statistics.visibility.percent'; dir: 'asc' | 'desc'; }; /** * Liczba wierszy na stronę. * @default 10 */ limit?: number; /** * Numer strony. * @default 1 */ page?: number; /** * Opcjonalne filtrowanie wyników. Kontroler przyjmuje ten parametr (wg źródła), * ale zestaw dozwolonych kluczy filtrów dla raportu URL-i **nie został jeszcze * zweryfikowany na żywo** — używaj ostrożnie. */ filtering?: unknown; } export default HistoryUrlsGetLostRequest ``` > **Ostrzeżenie:** > **`order` to pojedynczy obiekt** (`{ prop, dir }`) — nie tablica. Ten raport dopuszcza wyłącznie 4 właściwości sortowania (`statistics.visibility.*`) — próba sortowania np. po `keyword` lub `statistics.position.current` zakończy się błędem `418`. > **Ostrzeżenie:** > Wymagane są: **`domain`**, **`fetch_mode`**, **`country_id`**, **`date_min`**, **`date_max`** oraz pojedynczy obiekt **`order`** (`{ prop, dir }` — nie tablica). Dozwolone są **tylko 4** wartości `order.prop` (właściwości `statistics.visibility.*`) — mniej niż w raporcie fraz, który ma ich 11. Wartość `fetch_mode: "domain"` **nie istnieje** — użyj `topLevelDomain`. Uwaga na typy: część pól liczbowych przychodzi jako **stringi** (`keywords_count`, `statistics.wins.current`, `statistics.losses.current`). ## Odpowiedź W przypadku powodzenia otrzymujesz `data` (tablicę wierszy z URL-ami) oraz `pagination`. Dla zapytania (`zalando.pl`, 2026-06-20 → 2026-06-29) raport zwrócił `count` = 2 983 utraconych URL-i. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "url": "zalando.pl/ochnik/", "keywords_count": "5", "statistics": { "visibility": { "current": 22678.5, "previous": 79197.19, "diff": -56518.69 } /* … */ } } ], "pagination": { "page_count": 1492, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 2983, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "url": "zalando.pl/ochnik/", "keywords_count": "5", "statistics": { "top3": { "current": 0, "previous": 2, "diff": -2, "percent": -1 }, "top10": { "current": 3, "previous": 2, "diff": 1, "percent": 0.5 }, "top50": { "current": 2, "previous": 1, "diff": 1, "percent": 1 }, "visibility": { "current": 22678.5, "previous": 79197.19, "diff": -56518.69, "percent": -0.7136 }, "position": { "current": 12, "previous": 7, "diff": 5 }, "summary_position": { "current": 63, "previous": 38, "diff": 25, "percent": 0.6579 }, "wins": { "current": "0" }, "losses": { "current": "5" } } }, { "url": "zalando.pl/akcesoria-torby-kobiety/pinko/", "keywords_count": "1", "statistics": { "top3": { "current": 1, "previous": 1, "diff": 0, "percent": 0 }, "top10": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "top50": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "visibility": { "current": 5321.25, "previous": 8672.4, "diff": -3351.15, "percent": -0.3864 }, "position": { "current": 3, "previous": 2, "diff": 1 }, "summary_position": { "current": 3, "previous": 2, "diff": 1, "percent": 0.5 }, "wins": { "current": "0" }, "losses": { "current": "1" } } } ], "pagination": { "page_count": 1492, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 2983, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type HistoryUrlsGetLostResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Zwrócone wiersze z URL-ami */ data: UrlRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }; } type UrlRow = { /** Adres URL (bez protokołu) */ url: string; /** Liczba fraz rankujących na ten URL. **Uwaga: string, nie number.** */ keywords_count: string; statistics: { /** Liczba fraz URL-a w TOP 3 (`{ current, previous, diff, percent }`) */ top3: RangeStat; /** Liczba fraz URL-a w TOP 10 */ top10: RangeStat; /** Liczba fraz URL-a w TOP 50 */ top50: RangeStat; /** Widoczność — szacowany ruch */ visibility: RangeStat; /** Średnia pozycja (bez pola percent) */ position: { current: number; previous: number; diff: number }; /** Suma pozycji */ summary_position: RangeStat; /** Liczba fraz, które zyskały w tym URL-u. **Uwaga: string, nie number.** */ wins: { current: string }; /** Liczba fraz, które straciły w tym URL-u. **Uwaga: string, nie number.** */ losses: { current: string }; }; } type RangeStat = { current: number; previous: number; diff: number; percent: number; } export default HistoryUrlsGetLostResponse ``` ## Błędy ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data, database, timeout, unknown */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > **`418`** zwracany jest również dla błędów walidacji — nie tylko przy ograniczeniu liczby żądań (rate limiting). Nieznane `country_id` → `418` z komunikatem "Unknown country\_id". Niedozwolony `order.prop` → `418` `invalid_data` z komunikatem "This value is not allow. Please use correct colum name" (pisownia oryginalna). > > **Znany błąd — odwrócony komunikat.** Gdy `date_min` jest **późniejszy** niż `date_max`, reguła `DateRangeRules` zwraca komunikat `"date_max must be less or equal than date_min"` — treść jest odwrócona; należy go odczytywać jako naruszenie reguły zakresu dat, a nie jako dosłowną instrukcję. ## Powiązane akcje - `getData` — pełna lista URL-i w zakresie dat (taka sama struktura żądania) - `getWins` — URL-e, których widoczność wzrosła w zakresie dat - `getLosses` — URL-e, których widoczność spadła w zakresie dat - `getAcquired` — URL-e nowo pozyskane (zaczęły rankować w badanym okresie) - `getLost` — URL-e utracone (`MODE_LOSE`, ta strona)