---
title: "AI Overviews: frazy (`getKeywords`)"
source: https://docs.senuto.com/modules/visibility_analysis/va-ai-overviews-getKeywords
api: POST /api/visibility_analysis/reports/ai_overviews/getKeywords
---

# AI Overviews: frazy (`getKeywords`)

**`POST /api/visibility_analysis/reports/ai_overviews/getKeywords`**

> **Ostrzeżenie:**
> **Endpoint przestarzały.** Działa, ale może nie być aktywnie utrzymywany i w przyszłości zostać wycofany lub zastąpiony — co może też tłumaczyć, dlaczego zwraca pustą listę mimo obecności danych AIO. Planuj integrację z ostrożnością.

Zwraca frazy kluczowe, dla których domena pojawia się w sekcji **AI Overviews** Google (generatywne podsumowania wyświetlane nad wynikami organicznymi), wraz ze statystykami pozycji, widoczności, ruchu oraz cech SERP dla każdej frazy. Kształt żądania i odpowiedzi jest spójny z pozostałymi raportami kontrolera `visibility_analysis/reports`.

---

## Żądanie

`POST` `/api/visibility_analysis/reports/ai_overviews/getKeywords`

Nagłówki: `Authorization: Bearer <token>`, `Content-Type: application/json`.

### Struktura żądania

**Podstawowy**

```jsonc filename="żądanie-podstawowe.jsonc"
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "limit": 2
}
```

**Rozszerzony**

```jsonc filename="żądanie-rozszerzone.jsonc"
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "limit": 10,
  "page": 1,
  "with_history": true,
  "order": { "prop": "visibility", "dir": "desc" },
  "filtering": []
}
```

**cURL**

```bash
curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/ai_overviews/getKeywords' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "limit": 2 }'
```

### Parametry

```ts
type AiOverviewsGetKeywordsRequest = {
/**
 * **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; "domena")
 * - `subdomain` — pojedyncza subdomena
 * - `catalog` — ścieżka/katalog
 * - `url` — dokładny URL
 */
fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url';
/**
 * Liczba wierszy na stronę. Nieujemna liczba całkowita.
 * @default 10
 */
limit?: number;
/**
 * Numer strony. Nieujemna liczba całkowita.
 * @default 1
 */
page?: number;
/**
 * Dołącz do odpowiedzi mapę historii pozycji (`history`) dla każdej frazy.
 * @default true
 */
with_history?: boolean;
/**
 * Sortowanie wyników — **pojedynczy obiekt**, nie tablica.
 * Dozwolone `prop` m.in.: `keyword`, `organic_pos`, `visibility`,
 * `searches`, `best_aio_pos`, `aio_positions_count`, `aio_domains_count`.
 * Zły kształt lub nieznany klucz NIE zwraca błędu — API po cichu wraca
 * do sortu domyślnego (`best_organic_pos` rosnąco, `searches` malejąco).
 */
order?: { prop: string; dir: 'asc' | 'desc' };
/**
 * Dyrektywy filtrowania. Pusta tablica = brak filtrowania.
 */
filtering?: unknown[];
}
export default AiOverviewsGetKeywordsRequest
```

> **Ostrzeżenie:**
> Nazwy parametrów: jest to **`filtering`** (nie `filters`) oraz **`order`** (nie `sort_by` / `sort_order`). Uwaga na kształt `order`: to **obiekt `{ "prop": …, "dir": … }`** — forma tablicowa `[{ field, direction }]` jest przez API **ignorowana po cichu** (zwraca 200 z sortem domyślnym). Kierunku sortowania nie udało się potwierdzić na żywym API, bo raport zwraca pustą listę (patrz ostrzeżenie o statusie `@deprecated` powyżej) — kształt na podstawie źródła backendu.

> **Ostrzeżenie:**
> Zarówno **`domain`**, jak i **`fetch_mode`** są **wymagane**; pominięcie `fetch_mode` zwraca `418` z `invalid_data`. Metoda to **`POST`** z treścią JSON — przesłanie parametrów inną drogą skutkuje `405`/`418`.

> **Ostrzeżenie:**
> Przykładowa domena nie zwróciła danych dla tego raportu (`data` jest puste, `count` = `0`) — poniżej udokumentowano **strukturę odpowiedzi** na podstawie analizy kontrolera, bez zmyślania wartości. Dla domeny obecnej w AI Overviews `data` zawiera wiersze fraz o kształcie analogicznym do raportu pozycji.

## Odpowiedź

Po pomyślnym żądaniu otrzymujesz `data` (tablicę wierszy fraz, dla których domena pojawia się w AI Overviews) oraz `pagination`. Gdy domena nie występuje w AI Overviews, `data` jest puste, a `count` wynosi `0`.

**Skrócona**

```json filename="przykładowa-odpowiedź (skrócona)"
{
  "success": true,
  "data": [],
  "pagination": { "count": 0, "page_count": 0, "current_page": 1, "limit": 2 }
}
```

**Pełna**

```json filename="przykładowa-odpowiedź (200)"
{
  "success": true,
  "data": [],
  "pagination": {
    "page_count": 0,
    "current_page": 1,
    "has_next_page": false,
    "has_prev_page": false,
    "count": 0,
    "limit": 2
  }
}
```

### Struktura odpowiedzi

```ts
type AiOverviewsResponse = {
/** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */
success: boolean;
/** Zwrócone wiersze fraz; puste, gdy domena nie pojawia się w AI Overviews */
data: KeywordRow[];
/** Metadane paginacji */
pagination: {
  page_count: number;
  current_page: number;
  has_next_page: boolean;
  has_prev_page: boolean;
  count: number;
  limit: number;
};
}

type KeywordRow = {
keyword_id: number;
kid: string;
domain: string;
keyword: string;
words_count: number;
statistics: {
  position: { current: number; previous: number; diff: number; changes: { wins: number; losses: number; no_changes: number }; history: Record<string, { position: number; has_serp: boolean }> | [] };
  visibility: { current: number; previous: number; diff: number; percent: number; history: null };
  url: { current: string; previous: string; is_change: 0 | 1 };
  cpc: { current: number };
  searches: { current: number };
  trends: { history: number[]; peak: number | null };
  difficulty: { current: number };
  snippets: { current: string[] };
};
}
export default AiOverviewsResponse
```

## Błędy

```ts
type ErrorResponse = {
success: false;
data: {
  error: {
    /** np. invalid_data, invalid_filtering, unreachable_data, timeout, database, unknown */
    type: string;
    message: string;
    /** pole -> reguła -> komunikat (dla invalid_data) */
    params?: Record<string, Record<string, string>>;
  };
};
}
export default ErrorResponse
```

> **Błąd:**
> **`418`** jest zwracane również w przypadku błędów walidacji — nie tylko przy ograniczaniu liczby żądań. Brak `fetch_mode` →
> `{"success":false,"data":{"error":{"type":"invalid_data","params":{"fetch_mode":{"_required":"This field is required"}}}}}`.

## Powiązane akcje

- `getKeywords` — frazy z AI Overviews (ta strona)
- `getData` — bieżące pozycje organiczne (raport `positions`, taki sam kształt żądania)
- `getWins` / `getLosses` — frazy, które zyskały / straciły pozycje
- `getKeywordHistory` — pełna historia pozycji dla pojedynczej frazy (`keyword_id` + `kid` + `domain` + `fetch_mode`)