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

# AI Overviews: szanse (`getOpportunities`)

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

> **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 listę **fraz-szans w AI Overviews (AIO)** — zgodnie z adnotacją w kodzie źródłowym są to słowa kluczowe, dla których **istnieje blok AI Overview** i analizowana domena **rankuje organicznie**, ale **nie pojawia się w samym AIO** jako cytowane źródło. To naturalni kandydaci do optymalizacji treści: domena ma już autorytet organiczny dla tych zapytań, a mimo to nie jest obecna w odpowiedziach generowanych przez AI.

---

## Żądanie

`POST` `/api/visibility_analysis/reports/ai_overviews/getOpportunities`

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

**Rozszerzony**

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

**cURL**

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

### Parametry

```ts
type AiOverviewsGetOpportunitiesRequest = {
/**
 * **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;
/**
 * Filtrowanie listy szans (AI Overviews). Dozwolone klucze m.in.: `keywords`, `searches`,
 * `organic_pos`, `organic_url`, `organic_vis`, `aio_positions_count`, `aio_domains_count`,
 * `aio_length`, `aio_text` oraz `intentions.primary_intent` / `intentions.main_intent` /
 * `intentions.action_type` / `intentions.journey_stage` / `intentions.content_timeliness`.
 * ⚠️ **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 AiOverviewsGetOpportunitiesRequest
```

> **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ę fraz-szans AI Overviews — oraz obiekt `pagination` z informacjami o stronicowaniu. Gdy dla danej domeny 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 AiOverviewsOpportunitiesResponse = {
/** Flaga przetworzenia żądania. Potwierdzone (`true`) w odpowiedzi `200`. */
success: boolean;
/**
 * Tablica fraz-szans: dla frazy istnieje AI Overview i domena rankuje organicznie,
 * ale nie jest obecna w AIO. 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 AiOverviewsOpportunitiesResponse
```

## 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
- `getKeywordsIntents` — agregacja fraz AIO według intencji
- `getOpportunities` — frazy-szanse: domena rankuje organicznie, ale nie jest w AIO (ta strona)

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