--- title: "Historia fraz: pozyskane (`getAcquired`)" source: https://docs.senuto.com/modules/visibility_analysis/va-history-keywords-getAcquired api: POST /api/visibility_analysis/reports/history/keywords/getAcquired --- # Historia fraz: pozyskane (`getAcquired`) **`POST /api/visibility_analysis/reports/history/keywords/getAcquired`** Zwraca frazy **pozyskane** w zadanym zakresie dat: na `date_min` domena nie rankowała w TOP50, a na `date_max` już rankuje (tryb `MODE_GAIN` tego samego komponentu danych co `getData`). W zwracanych wierszach `statistics.position.previous` ma zawsze wartość sentinela `51` (poza TOP50), `statistics.url.previous` jest puste, `statistics.url.is_change` = `1`, a `statistics.visibility.percent` = `1` (100% wzrostu z zera). Struktura żądania jest identyczna jak w `getData`. > **Ostrzeżenie:** > **Te wiersze pojawiają się również w [`getWins`](/modules/visibility_analysis/va-history-keywords-getWins).** Fraza pozyskana ma `position.previous = 51`, więc jej `diff` jest ujemny i spełnia także warunek wzrostu. `getAcquired` jest podzbiorem `getWins` — **sklejanie obu list zdubluje wiersze**. > > Uwaga: w drugą stronę jest inaczej. [`getLost`](/modules/visibility_analysis/va-history-keywords-getLost) i [`getLosses`](/modules/visibility_analysis/va-history-keywords-getLosses) są rozłączne i tam sklejenie jest poprawne. Ta asymetria może się w przyszłości ujednolicić. | Fraza | ID frazy | KID | Domena | Liczba słów | Pozycja | Pozycja poprz. | Zmiana pozycji | Wzrosty | Spadki | Bez zmian | Widoczność | Widoczność poprz. | Δ widoczności | Widoczność % | URL bieżący | URL poprzedni | URL zmiana | CPC | Wyszukiwania/mies. | Trend (12 mies.) | Szczyt trendu | Trudność | Snippety SERP | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | plecak nike | 12682481 | abe87dec4fc0e9b7386f2718c0092aa2 | zalando.pl | 2 | 5 | 51 | -46 | 0 | 1 | 0 | 2489.85 | 0 | 2489.85 | 1 | zalando.pl/akcesoria-plecaki/nike/ | | 1 | 0.53 | 49500 | [27100,33100,90500,201000,49500,22200,27100,27100,22200,22200,27100,22200] | | 60 | ["image_thumbs"] | | air force 1 mid | 16378096 | dde117ca968b0e7a3cfc124ca6660b30 | zalando.pl | 4 | 2 | 51 | -49 | 0 | 0 | 0 | 946.08 | 0 | 946.08 | 1 | zalando.pl/obuwie/?q=air+force+1+mid | | 1 | 0.8 | 5400 | [5400,3600,4400,2900,2400,1900,2400,5400,8100,9900,9900,8100] | | 46 | ["image_thumbs"] | _zalando.pl, sort: widoczność malejąco — frazy pozyskane w zakresie. Poprzednia pozycja `51` to sentinel „poza TOP50”. Wszystkie pola wiersza (poza mapą historii `statistics.position.history`, która ma zmienne klucze-daty — jest w JSON i sekcji „Struktura odpowiedzi”)._ --- ## Żądanie `POST` `/api/visibility_analysis/reports/history/keywords/getAcquired` 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/keywords/getAcquired' \ --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 HistoryKeywordsGetAcquiredRequest = { /** * **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**. Początek zakresu dat, `YYYY-MM-DD`. Na tę datę domena **nie** rankowała w TOP50 na zwracane frazy. * Dostępne daty pobierzesz akcją `getDates`. */ date_min: string; /** * **Wymagane**. Koniec zakresu dat, `YYYY-MM-DD`. Na tę datę domena rankuje na zwracane frazy. */ date_max: string; /** * **Wymagane**. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` "Unknown country_id". */ country_id: number; /** * **Wymagane**. **Pojedyncza** dyrektywa sortowania (jeden obiekt — nie tablica). * `prop` to jedna z dozwolonych właściwości sortowalnych; `dir` to kierunek. * * Dozwolone wartości `prop`: * - `keyword` * - `statistics.position.current` * - `statistics.position.previous` * - `statistics.position.diff` * - `statistics.visibility.current` * - `statistics.visibility.previous` * - `statistics.visibility.diff` * - `statistics.difficulty.current` * - `statistics.searches.current` * - `statistics.cpc.current` * - `statistics.url.is_change` * * Błędny `prop` → `418` `invalid_data` z komunikatem "This value is not allow. Please use correct colum name". */ order: { prop: | 'keyword' | 'statistics.position.current' | 'statistics.position.previous' | 'statistics.position.diff' | 'statistics.visibility.current' | 'statistics.visibility.previous' | 'statistics.visibility.diff' | 'statistics.difficulty.current' | 'statistics.searches.current' | 'statistics.cpc.current' | 'statistics.url.is_change'; dir: 'asc' | 'desc'; }; /** * Liczba wierszy na stronę. * @default 10 */ limit?: number; /** * Numer strony. * @default 1 */ page?: number; /** * Tablica grup filtrów — ten sam mechanizm i te same klucze co w `positions/getData` * oraz `history/keywords/getData`. Szczegóły: [typy filtrów](/types/filter). */ filtering?: FilterGroup[]; } export default HistoryKeywordsGetAcquiredRequest ``` > **Ostrzeżenie:** > **`order` to pojedynczy obiekt** (`{ prop, dir }`) — nie tablica. Używaj ścieżek `prop` z kropkami wymienionych powyżej; inne wartości zwracają `418` z komunikatem `"This value is not allow. Please use correct colum name"`. > **Ostrzeżenie:** > Pięć parametrów jest **wymaganych**: **`domain`**, **`fetch_mode`**, **`date_min`**, **`date_max`** oraz **`country_id`**, a także pojedynczy obiekt **`order`** (`{ prop, dir }` — nie tablica). Wartość `fetch_mode` = `"domain"` **nie istnieje** — używaj `topLevelDomain`. Nieznane `country_id` zwraca `418` z komunikatem `"Unknown country_id"`. Pozycja `51` to sentinel oznaczający „poza TOP50" — nie rzeczywistą pozycję w SERP. ## Odpowiedź W przypadku powodzenia otrzymujesz `data` (tablicę wierszy z frazami pozyskanymi) oraz `pagination`. Charakterystyka trybu `MODE_GAIN`: `position.previous` = `51` (sentinel „poza TOP50"), `url.previous` = `""`, `url.is_change` = `1` (liczbowo), `visibility.previous` = `0`, `visibility.percent` = `1`. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "keyword_id": 12682481, "keyword": "plecak nike", "statistics": { "position": { "current": 5, "previous": 51 }, "visibility": { "current": 2489.85, "previous": 0, "percent": 1 } /* … */ } } ], "pagination": { "page_count": 1812, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 3623, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "keyword_id": 12682481, "kid": "abe87dec4fc0e9b7386f2718c0092aa2", "domain": "zalando.pl", "keyword": "plecak nike", "words_count": 2, "statistics": { "position": { "current": 5, "previous": 51, "diff": -46, "changes": { "wins": 0, "losses": 1, "no_changes": 0 }, "history": { "2026-05-25": { "position": 0, "has_serp": true }, "2026-06-26": { "position": 5, "has_serp": true } } }, "visibility": { "current": 2489.85, "previous": 0, "diff": 2489.85, "percent": 1, "history": null }, "url": { "current": "zalando.pl/akcesoria-plecaki/nike/", "previous": "", "is_change": 1 }, "cpc": { "current": 0.53 }, "searches": { "current": 49500 }, "trends": { "history": [27100, 33100, 90500, 201000, 49500, 22200, 27100, 27100, 22200, 22200, 27100, 22200], "peak": null }, "difficulty": { "current": 60 }, "snippets": { "current": ["image_thumbs"] } } }, { "keyword_id": 16378096, "kid": "dde117ca968b0e7a3cfc124ca6660b30", "domain": "zalando.pl", "keyword": "air force 1 mid", "words_count": 4, "statistics": { "position": { "current": 2, "previous": 51, "diff": -49, "changes": { "wins": 0, "losses": 0, "no_changes": 0 }, "history": { "2026-06-26": { "position": 2, "has_serp": true } } }, "visibility": { "current": 946.08, "previous": 0, "diff": 946.08, "percent": 1, "history": null }, "url": { "current": "zalando.pl/obuwie/?q=air+force+1+mid", "previous": "", "is_change": 1 }, "cpc": { "current": 0.8 }, "searches": { "current": 5400 }, "trends": { "history": [5400, 3600, 4400, 2900, 2400, 1900, 2400, 5400, 8100, 9900, 9900, 8100], "peak": null }, "difficulty": { "current": 46 }, "snippets": { "current": ["image_thumbs"] } } } ], "pagination": { "page_count": 1812, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 3623, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type HistoryKeywordsGetAcquiredResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Zwrócone wiersze z frazami pozyskanymi */ data: AcquiredKeywordRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }; } type AcquiredKeywordRow = { keyword_id: number; kid: string; domain: string; keyword: string; words_count: number; statistics: { /** `previous` = 51 — sentinel "poza TOP50" (fraza pozyskana) */ position: { current: number; previous: 51; diff: number; changes: { wins: number; losses: number; no_changes: number }; history: Record }; /** `previous` = 0, `percent` = 1 (100% wzrostu z zera) */ visibility: { current: number; previous: 0; diff: number; percent: 1; history: null }; /** `previous` puste, `is_change` = 1 (liczbowo 0/1) */ url: { current: string; previous: ''; is_change: 1 }; cpc: { current: number }; searches: { current: number }; trends: { history: number[]; peak: number | null }; difficulty: { current: number }; snippets: { current: string[] }; }; } export default HistoryKeywordsGetAcquiredResponse ``` ## Błędy ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > **`418`** zwracany jest dla błędów walidacji. Brak wymaganego pola → `invalid_data`; nieznane `country_id` → `"Unknown country_id"`; błędny `order.prop` → `"This value is not allow. Please use correct colum name"`. > > **Znany błąd — odwrócony komunikat.** Przy `date_min > date_max` komunikat reguły `DateRangeRules` brzmi `"date_max must be less or equal than date_min"` — treść jest odwrócona; należy go odczytywać jako niepowodzenie reguły zakresu dat, a nie jako dosłowną instrukcję. ## Powiązane akcje - [`getData`](/modules/visibility_analysis/va-history-keywords) — frazy w zakresie dat (`MODE_DATA`) - `getWins` / `getLosses` — frazy, które zyskały / straciły pozycje w danym zakresie (taka sama struktura żądania) - `getAcquired` — frazy nowo pozyskane w zakresie (ta strona) - [`getLost`](/modules/visibility_analysis/va-history-keywords-getLost) — frazy całkowicie utracone w zakresie (taka sama struktura żądania) - `getDates` — dostępne daty dla zakresu (POST, wymaga tylko `country_id`)