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

# AI Overviews: szanse (`getOpportunities`)

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

Zwraca stronicowaną listę fraz projektu, dla których istnieje blok **AI Overview**, a monitorowana domena **rankuje organicznie, ale nie jest cytowana w AIO** — czyli potencjalne szanse optymalizacyjne (semantyka potwierdzona adnotacją w kodzie źródłowym kontrolera). Ten raport — w odróżnieniu od AI Overviews w Analizie widoczności — **nie jest przestarzały**.

---

## Żądanie

`POST` `/api/rank_tracker/reports/ai_overviews/getOpportunities`

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

### Struktura żądania

**Podstawowy**

```jsonc filename="żądanie-podstawowe.jsonc"
{
  "project_id": null
}
```

**Rozszerzony**

```jsonc filename="żądanie-rozszerzone.jsonc"
{
  "project_id": null,
  "limit": 2,
  "page": 1
}
```

**cURL**

```bash
curl --location --request POST 'https://api.senuto.com/api/rank_tracker/reports/ai_overviews/getOpportunities' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "project_id": null, "limit": 2 }'
```

### Parametry

```ts
type GetAiOverviewsOpportunitiesRequest = {
/**
 * **Wymagane**. ID projektu Rank Tracker (kontrola dostępu `ProjectAccessRules`).
 * Musi należeć do użytkownika — cudzy lub nieistniejący `project_id` zwraca `418` z komunikatem `Unauthorized access`.
 * Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
 */
project_id: number;
/**
 * Rozmiar strony paginacji. Odbija się w `pagination.limit`.
 * @default 10
 */
limit?: number;
/**
 * Numer strony paginacji.
 * @default 1
 */
page?: number;
}
export default GetAiOverviewsOpportunitiesRequest
```

> **Informacja:**
> Endpoint przyjmuje także `filtering` i `order` — oba korzystają z rejestrów filtrów i sortowania dla raportów AI Overviews. Nieznany klucz filtra zwraca `418` z `invalid_filtering`.

> **Ostrzeżenie:**
> Projekt, który nie ma danych AI Overviews, zwraca `200` z **pustą tablicą** `data` — to nie błąd, tylko brak wyników dla tego projektu. Poniżej opisana jest koperta odpowiedzi.

## Odpowiedź

Po pomyślnym żądaniu otrzymujesz standardową kopertę: `success`, `data` (tablica fraz-szans) oraz `pagination`. Dla projektu bez danych AIO tablica `data` jest pusta, a `pagination.count` wynosi `0`.

**Skrócona**

```json filename="przykładowa-odpowiedź (skrócona)"
{
  "success": true,
  "data": [],
  "pagination": { "page_count": 0, "current_page": 1, "has_next_page": false, "has_prev_page": false, "count": 0, "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 GetAiOverviewsOpportunitiesResponse = {
/** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */
success: boolean;
/**
 * Frazy z istniejącym AI Overview, w których domena rankuje organicznie, ale nie jest cytowana.
 * Kształt wiersza zależy od danych AI Overviews projektu.
 */
data: unknown[];
/** Metadane paginacji */
pagination: {
  page_count: number;
  current_page: number;
  has_next_page: boolean;
  has_prev_page: boolean;
  count: number;
  /** Wartość przekazanego `limit` */
  limit: number;
};
}
export default GetAiOverviewsOpportunitiesResponse
```

## 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<string, Record<string, string>>;
  };
};
}
export default ErrorResponse
```

> **Błąd:**
> **`418`** jest zwracane przy błędach walidacji i braku dostępu: brak `project_id` → `invalid_data`, a cudzy lub nieistniejący `project_id` → `Unauthorized access` (`ProjectAccessRules`), nie `404`.

## Powiązane akcje

- `getStatistics` — zbiorcze statystyki AI Overviews projektu
- `getKeywords` — frazy wyzwalające AI Overviews
- `getDistribution` — rozkład obecności w AI Overviews
- `getCompetitors` — konkurenci cytowani w AI Overviews
- `getOpportunities` — szanse optymalizacyjne AIO (ta strona)
- `getAioDetails` — pełny surowy blok AI Overview danej frazy (`project_id` + `keyword_id`)
- `getAioSources` — lista źródeł cytowanych w bloku AIO danej frazy (`project_id` + `keyword_id`)