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

żądanie-podstawowe.jsonc


{
  "project_id": null
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "project_id": null,
  "limit": 2,
  "page": 1
}

cURL


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

Name	Type	Default
`project_id`	`number` 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`.
`limit`	`number` Rozmiar strony paginacji. Odbija się w `pagination.limit`.	`10`
`page`	`number` Numer strony paginacji.	`1`

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.

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

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

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`unknown[]` 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.
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }` Metadane paginacji

Błędy

Name	Type	Default
`success`	`false`
`data`	`{ error: { type: string; message: string; params?: Record<string, Record<string, string>>; }; }`

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)

AI Overviews: szanse (getOpportunities)