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

# AI Overviews: wyniki frazy (`getKeywordResults`)

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

> **Ostrzeżenie:**
> **Endpoint przestarzały.** Działa, ale może nie być aktywnie utrzymywany i w przyszłości zostać wycofany lub zastąpiony. Planuj integrację z ostrożnością. Aktualne odpowiedniki raportów AI Overviews per projekt znajdziesz w module **Monitoring** (`rank_tracker/reports/ai_overviews`).

Zwraca **wyniki AI Overviews (AIO) dla pojedynczej frazy** — szczegóły obecności źródeł w bloku AI Overviews dla konkretnego słowa kluczowego wskazanego identyfikatorem `keyword_id`. Raport pozwala sprawdzić, jak wygląda blok AIO dla wybranego zapytania w kontekście analizowanej domeny.

---

## Żądanie

`POST` `/api/visibility_analysis/reports/ai_overviews/getKeywordResults`

Parametry przesyłasz w **treści żądania jako JSON**. Nagłówki: `Authorization: Bearer <token>` oraz `Content-Type: application/json`.

### Struktura żądania

**Podstawowy**

```jsonc filename="żądanie-podstawowe.jsonc"
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1,
  "keyword_id": null
}
```

**Rozszerzony**

```jsonc filename="żądanie-rozszerzone.jsonc"
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1,
  "keyword_id": null,
  "limit": 2
}
```

**cURL**

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

### Parametry

```ts
type AiOverviewsGetKeywordResultsRequest = {
/**
 * **Wymagane**. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`.
 * Bez schematu/protokołu — np. `zalando.pl`.
 */
domain: string;
/**
 * **Wymagane**. Sposób interpretacji `domain`.
 * Uwaga: `domain` NIE jest prawidłową wartością — dla całej domeny użyj `topLevelDomain`.
 * - `topLevelDomain` — cała domena (najczęstszy przypadek)
 * - `subdomain` — pojedyncza subdomena
 * - `catalog` — ścieżka/katalog
 * - `url` — dokładny adres URL
 */
fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url';
/**
 * Identyfikator kraju (baza Google). Opcjonalne — walidator tej akcji nie wymusza pola;
 * gdy pominięte, backend stosuje domyślny kraj (PL).
 * @default 1
 */
country_id?: number;
/**
 * **Wymagane** (walidator: requirePresence). Identyfikator słowa kluczowego, dla którego
 * mają zostać zwrócone wyniki AI Overviews.
 * Identyfikatory fraz uzyskasz np. z akcji `getKeywords` tego kontrolera.
 */
keyword_id: number;
/**
 * Filtrowanie wyników AI Overviews frazy. Dozwolone klucze m.in.: `domain`, `pos`, `url`, `title`,
 * `organic_pos`, `organic_url`, `faq_pos`, `faq_url`, `is_translated`, `is_fragment`,
 * `fragment_text`, `is_analyzed_domain_and_url_match`.
 * ⚠️ **Uwaga:** backend AIO działa na ClickHouse i — inaczej niż raporty Bazy słów — na
 * nieznany `key` **nie** zwraca `418` (klucz bywa po cichu pomijany). Efektu filtra nie
 * wsparcie potwierdzone w implementacji endpointu.
 */
filtering?: Array<{
  filters: Array<{ key: string; match?: 'gt' | 'gte' | 'lt' | 'lte' | 'eq'; value: string | number | Array<string | number>; complement?: boolean }>;
  conjunction?: 'and' | 'or';
}>;
/**
 * Numer strony wyników. Opcjonalne.
 * @default 1
 */
page?: number;
/**
 * Maksymalna liczba wyników na stronę. Opcjonalne.
 */
limit?: number;
}
export default AiOverviewsGetKeywordResultsRequest
```

> **Ostrzeżenie:**
> Dozwolone wartości `fetch_mode` to dokładnie `['topLevelDomain', 'subdomain', 'catalog', 'url']` — przekazanie `domain` to częsty błąd i nie przechodzi walidacji.

> **Ostrzeżenie:**
> Domena bez danych AI Overviews zwraca `200` z **pustą tablicą** `data` — to nie błąd, tylko brak wyników dla tej domeny.

## Odpowiedź

W przypadku powodzenia otrzymujesz `success: true`, `data` — tablicę wyników AI Overviews dla wskazanej frazy — oraz obiekt `pagination` z informacjami o stronicowaniu. Gdy dla danej domeny (lub frazy) brak danych AIO, `data` jest pustą tablicą (`[]`), a liczniki paginacji wskazują zero wyników. Tak właśnie odpowiedziała domena testowa `zalando.pl` — `200` z pustą tablicą.

**Skrócona**

```json filename="przykładowa-odpowiedź (skrócona)"
{
  "success": true,
  "data": []
}
```

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

> **Ostrzeżenie:**
> Dla domen, które nie mają danych AI Overviews, `data` jest **pustą tablicą** — to nie błąd, tylko brak wyników dla tej domeny. Poniżej opisana jest koperta odpowiedzi.

### Struktura odpowiedzi

```ts
type AiOverviewsKeywordResultsResponse = {
/** Flaga przetworzenia żądania. Potwierdzone (`true`) w odpowiedzi `200`. */
success: boolean;
/**
 * Tablica wyników AI Overviews dla wskazanej frazy.
 * Pusta tablica (`[]`), gdy domena nie ma danych AIO.
 */
data: unknown[];
/** Informacje o stronicowaniu wyników. Potwierdzone w odpowiedzi `200`. */
pagination: {
  /** Łączna liczba stron wyników. */
  page_count: number;
  /** Numer bieżącej strony. */
  current_page: number;
  /** Czy istnieje następna strona. */
  has_next_page: boolean;
  /** Czy istnieje poprzednia strona. */
  has_prev_page: boolean;
  /** Łączna liczba wyników. */
  count: number;
  /** Limit wyników na stronę (odzwierciedla przekazany `limit`). */
  limit: number;
};
}
export default AiOverviewsKeywordResultsResponse
```

## Błędy

```ts
type ErrorResponse = {
success: false;
data: {
  error: {
    /** np. invalid_data, 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:**
> Błędy walidacji (np. brak wymaganego `domain` lub `fetch_mode`, albo nieprawidłowa wartość `fetch_mode`) zwracane są ze statusem **`418`** i kopertą `invalid_data` z mapą `params` wskazującą pole i naruszoną regułę.

## Powiązane akcje

Wszystkie poniższe akcje są przestarzałe:

- `getStatistics` — zbiorcze statystyki AI Overviews dla domeny
- `getKeywords` — słowa kluczowe wywołujące AI Overviews
- `getDistribution` — rozkład obecności domeny w AI Overviews
- `getCompetitors` — konkurenci domeny w AI Overviews
- `getKeywordResults` — wyniki AI Overviews dla pojedynczej frazy (ta strona)
- `getKeywordsIntents` — agregacja fraz AIO według intencji
- `getOpportunities` — frazy-szanse: domena rankuje organicznie, ale nie jest w AIO

Aktualne odpowiedniki raportów AI Overviews **per projekt** znajdziesz w module **Monitoring** (`rank_tracker/reports/ai_overviews`).