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).

Podgląd · 6 z 27 kolumn

URL	Frazy	TOP3	TOP3 poprz.	TOP3 Δ	TOP3 %
zalando.pl/ochnik/	5	0	2	-2	-1
zalando.pl/akcesoria-torby-kobiety/pinko/	1	1	1	0	0

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 <token>, Content-Type: application/json.

Struktura żądania

Podstawowy

żą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

żą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


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

Name	Type	Default
`domain`	`string` Wymagane. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`.
`fetch_mode`	`"topLevelDomain" \| "subdomain" \| "catalog" \| "url"` 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
`country_id`	`number` Wymagane. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` z komunikatem “Unknown country_id”.
`date_min`	`string` Wymagane. Początek zakresu dat, `YYYY-MM-DD`. Musi być nie późniejszy niż `date_max`.
`date_max`	`string` Wymagane. Koniec zakresu dat, `YYYY-MM-DD`. Musi być nie wcześniejszy niż `date_min`.
`order`	`{ prop: "statistics.visibility.current" \| "statistics.visibility.previous" \| "statistics.visibility.diff" \| "statistics.visibility.percent"; dir: "asc" \| "desc"; }` 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).
`limit`	`number` Liczba wierszy na stronę.	`10`
`page`	`number` Numer strony.	`1`
`filtering`	`unknown` 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.

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.

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

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 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`UrlRow[]` Zwrócone wiersze z URL-ami
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }` Metadane paginacji

Błędy

Name	Type	Default
`success`	`false`
`data`	`{ error: { type: string; message: string; params?: Record<string, Record<string, string>>; }; }`

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)

Historia URL-i: utracone (getLost)