--- title: "Snippety SERP: historia (`getHistory`)" source: https://docs.senuto.com/modules/rank_tracker/rt-snippets-getHistory api: POST /api/rank_tracker/reports/snippets/getHistory --- # Snippety SERP: historia (`getHistory`) **`POST /api/rank_tracker/reports/snippets/getHistory`** Zwraca historię elementów SERP (snippetów) wykrytych dla fraz projektu Rank Tracker: dla każdej daty pomiaru z zakresu `date_min`–`date_max` raportowana jest liczba fraz projektu, dla których dany typ snippetu występuje w SERP. Wynik pozwala śledzić, jak zmienia się obecność poszczególnych typów snippetów (np. `people_also_ask`, `image_thumbs`, `featured_snippets`) w czasie. --- ## Żądanie `POST` `/api/rank_tracker/reports/snippets/getHistory` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" { "project_id": null, "date_min": "2026-06-20", "date_max": "2026-06-29" } ``` **cURL** ```bash curl --location --request POST 'https://api.senuto.com/api/rank_tracker/reports/snippets/getHistory' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{ "project_id": null, "date_min": "2026-06-20", "date_max": "2026-06-29" }' ``` ### Parametry ```ts type GetSnippetsHistoryRequest = { /** * **Wymagane**. ID projektu Rank Tracker (walidator `SnippetsValidator`). * Musi należeć do użytkownika, inaczej zwracane jest `418` z komunikatem `Unauthorized access`. * Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`. */ project_id: number; /** * **Wymagane**. Data początkowa zakresu w formacie `YYYY-MM-DD`. */ date_min: string; /** * **Wymagane**. Data końcowa zakresu w formacie `YYYY-MM-DD`. */ date_max: string; } export default GetSnippetsHistoryRequest ``` > **Ostrzeżenie:** > Znany bug walidacji: gdy `date_min` jest **późniejsze** niż `date_max`, reguły `DateRangeRules` zwracają błąd z **odwróconym komunikatem** (treść sugeruje odwrotny kierunek naruszenia). Pilnuj poprawnej kolejności dat po swojej stronie. > **Ostrzeżenie:** > **Pułapki tego endpointu:** (1) `data` to **obiekt keyed by daty pomiaru** (`YYYY-MM-DD`) — w zwalidowanej odpowiedzi znalazły się dokładnie dwa snapshoty, `date_max` i `date_min` (w tej kolejności), ale **kolejności kluczy nie traktuj jako gwarantowanej**. (2) Każdy snapshot to **mapa typ snippetu → liczba fraz** (klucze dynamiczne). (3) Zbiór typów snippetów **może się różnić między datami** — np. snapshot `2026-06-20` nie zawiera kluczy `featured_snippets` ani `answer_box`, które występują w `2026-06-29`; brakującego klucza nie interpretuj automatycznie jako zera bez własnej decyzji. (4) Odpowiedź **nie ma paginacji**. ## Odpowiedź Po pomyślnym żądaniu otrzymujesz `data` — **obiekt keyed by daty pomiaru**. Każdy snapshot to mapa: typ snippetu → liczba fraz projektu, dla których ten snippet występował w SERP w danym dniu. Zwróć uwagę, że listy typów mogą się różnić między datami (poniżej `2026-06-20` nie ma `featured_snippets` ani `answer_box`). **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": { "2026-06-29": { "image_thumbs": 28, "people_also_ask": 83, "related_searches": 94, "featured_snippets": 4 }, "2026-06-20": { "image_thumbs": 37, "people_also_ask": 71, "related_searches": 89 } } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": { "2026-06-29": { "news": 0, "image_thumbs": 28, "wiki_right": 12, "map": 0, "top_video": 0, "spell": 3, "top_info": 0, "top_bar": 0, "top_scholar": 0, "top_number_results": 0, "top_public_data": 0, "site_links": 0, "featured_answer": 0, "adwords": 0, "people_also_ask": 83, "people_also_search_products": 2, "related_searches": 94, "video_thumbs": 35, "videos_pack": 35, "featured_snippets": 4, "answer_box": 1 }, "2026-06-20": { "news": 0, "image_thumbs": 37, "wiki_right": 9, "map": 1, "top_video": 0, "spell": 3, "top_info": 0, "top_bar": 0, "top_scholar": 0, "top_number_results": 0, "top_public_data": 0, "site_links": 0, "featured_answer": 0, "adwords": 0, "related_searches": 89, "people_also_ask": 71, "video_thumbs": 28, "videos_pack": 28, "people_also_search_products": 1 } } } ``` ### Struktura odpowiedzi ```ts type GetSnippetsHistoryResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** * Obiekt keyed by data pomiaru (`YYYY-MM-DD`). To NIE jest tablica i NIE ma paginacji. * Kolejność kluczy nie jest gwarantowana. */ data: Record; } /** * Mapa: typ snippetu (klucz dynamiczny, np. `people_also_ask`, `image_thumbs`) * -> liczba fraz projektu z tym snippetem w SERP danego dnia. * Zbiór kluczy może się różnić między datami. */ type SnippetHistorySnapshot = Record; export default GetSnippetsHistoryResponse ``` ## Błędy ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data, unknown */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > Błędy walidacji zwracane są ze statusem **`418`**. Brak któregokolwiek z pól `project_id`, `date_min`, `date_max` → `invalid_data`. `project_id` nienależący do użytkownika → `Unauthorized access` (`418`), a nie `404`. Znany bug: przy `date_min` późniejszym niż `date_max` komunikat błędu z `DateRangeRules` jest odwrócony względem faktycznego naruszenia. ## Powiązane akcje - `getHistory` — liczba fraz z danym typem snippetu w SERP, per data pomiaru (ta strona) - `getStatistics` — porównanie dwóch snapshotów per typ snippetu, z pokryciem SERP (`serp_coverage`) i widocznością domeny (`POST`, `project_id` + `date_min` + `date_max`)