# Senuto — status danych: API dla agentów AI

Publiczne, tylko do odczytu API strony https://status.senuto.com. Odpowiada na pytania: czy dzisiejsze dane w Senuto są już zebrane,
jak świeża jest baza Analizy Widoczności, co wykazał audyt jakości danych i czy trwają jakieś sprawy (incydenty).
Wszystkie odpowiedzi to JSON (UTF-8), bez logowania. Czas lokalny: Europe/Warsaw. Treści po polsku.

Adres bazowy: https://status.senuto.com/api/public
Indeks: https://status.senuto.com/api/public/index.json — od razu podsumowanie (`summary`: stan usług, ocena danych z najnowszego dnia z listą
problemów, wiek danych, otwarte sprawy, 5 najnowszych komunikatów) i lista końcówek ze szczegółami. Na proste pytanie „czy z danymi wszystko w porządku?”
wystarczy indeks.

## Jak często dane się zmieniają

| Końcówka | Odświeżanie | Co zawiera |
|---|---|---|
| `/status.json` | co 15 minut | postęp dzisiejszego zbierania: Monitoring i Analiza Widoczności |
| `/audit.json` | raz dziennie, po zakończeniu zbierania Monitoringu | audyt jakości danych dnia: oceny i testy |
| `/data-age.json` | raz dziennie, w nocy, po dziennym odświeżeniu Analizy Widoczności | wiek danych w Analizie Widoczności (Polska) |
| `/issues.json` | przy zmianie | otwarte sprawy i rozwiązane w ostatnich 30 dniach |
| `/announcements.json` (`?type=`) | przy zmianie | komunikaty z typami, od najnowszego |

Odpowiedzi mogą być buforowane do 5 minut. Nie pytaj częściej niż co 5 minut.

## /status.json

`services[]`, po jednym na usługę:
- `monitoring`: `state` (`waiting` — cykl jeszcze nie ruszył, `collecting` — trwa zbieranie, `stalled` — wstrzymane,
  `done` — dzisiejsze dane zebrane), `progress_pct` (0–100), `eta` (przewidywane zakończenie, gdy trwa zbieranie),
  `finished_at`, `target_ready_by` (cel: dane gotowe do tej godziny), `typical_finish` (mediana z ostatnich dni),
  `today_hourly[]` (postęp godzina po godzinie), `last_days[]` (`status`: `done` / `unfinished` / `inprogress`; `progress_pct`).
- `visibility-analysis`: baza jest odświeżana porcjami każdego dnia (nie cała naraz). `state` (`collecting` — trwa odświeżanie,
  `paused` — przerwa w ciągu dnia, `stalled` — brak odświeżania od doby),
  `avg_daily_refresh_pct` (jaka część bazy jest odświeżana dziennie), `full_refresh_days` (w ilu dniach odświeża się cała baza
  przy obecnym tempie), `target_full_refresh_days`, `last_days[]` (`refreshed_pct` bazy danego dnia; `complete` = pełny dzień).

Uwaga: po zakończeniu zbierania statystyki w aplikacji przeliczają się jeszcze przez pewien czas, więc nowe dane mogą się
pojawić w Senuto nieco później niż `finished_at`.

## /audit.json

`latest` — najnowszy dzień w całości, `days[]` — oceny z ostatnich 14 dni (najnowszy pierwszy). `?day=RRRR-MM-DD` zwraca jeden dzień.
- `verdict`: `ok` (można wierzyć danym), `warn` (z zastrzeżeniami), `bad` (dane z tego dnia niewiarygodne).
- `quality` — czy dane są poprawne; `technical` — czy są kompletne i zapisane. Każda: `score` 0–100 i `grade`
  A (od 85), B (od 70), C (od 55), D (od 40), E (poniżej). `tests`: zdane / z zastrzeżeniem / niezdane / bez pomiaru.
- `checks[]`: `status` (`ok`, `warn`, `bad`, `na` — brak pomiaru, `info` — informacja o Google, bez wpływu na ocenę),
  `value` (wynik dnia), `norm` (wartość zwykła), `about` (co test mierzy), `examples[]`, `points` / `penalty`
  (punkty przyznane / utracone z 100), `group` (`jakosc`, `techniczna`, `info`), `modules` (`monitoring`, `aw`).

## /data-age.json

Jak dawno frazy w bazie Analizy Widoczności (Polska) były ostatnio pobrane z Google: `age[]` (odsetek bazy w przedziałach
wieku), `refreshed_last_30_days_pct`, `by_monthly_searches[]` (popularniejsze frazy odświeżamy częściej; `median_age_days`).

## /issues.json

`open[]` i `resolved_recently[]`: `title`, `summary`, `status`, `stage` (`investigating`, `identified`, `fixing`,
`monitoring`, `resolved`), `since`, `url` (strona sprawy), `updates[]` (komunikaty, najnowszy pierwszy).

## /announcements.json

`announcements[]` od najnowszego: `date`, `type` (`problem`, `naprawa`, `aktualizacja`, `poprawka` — dane usunięte,
uzupełnione albo przeliczone wstecz, `zmiana` — zmiana w zbieraniu danych, `zapowiedz`, `informacja`), `title`, `text`,
`modules`, `pinned`, `url`. Opisy typów w `types`. Filtr: `?type=zmiana`.

## Jak odpowiadać użytkownikom

- „Czy dzisiejsze dane są już w Senuto?” → `/status.json`: `state` i `progress_pct` Monitoringu; przy `collecting` podaj `eta`.
- „Czy mogę ufać danym z dnia X?” → `/audit.json?day=X`: `verdict` i niezdane testy (`status` = `bad` / `warn`).
- „Jak stara jest pozycja w Analizie Widoczności?” → `/data-age.json`.
- „Czy coś się dzieje z danymi?” → `/issues.json` (`open[]`).
- „Co się ostatnio zmieniło w danych / zbieraniu danych?” → `/announcements.json` (np. `?type=zmiana` albo `?type=poprawka`).
Podawaj link do strony: https://status.senuto.com. Pytania: support@senuto.com.