AI Overviews: źródła (`getAioSources`)

POST/api/rank_tracker/reports/ai_overviews/getAioSources

Zwraca stronicowaną listę źródeł cytowanych w bloku AI Overview dla wskazanej frazy projektu Rank Tracker. W odróżnieniu od pozostałych akcji raportowych tego kontrolera wymaga — poza project_id — także keyword_id (kontrola dostępu KeywordAccessRules: fraza musi należeć do projektu). Pełny surowy blok AIO frazy (treść, nie tylko listę źródeł) zwraca uzupełniająca akcja getAioDetails (również project_id + keyword_id). Ten raport — w odróżnieniu od AI Overviews w Analizie widoczności — nie jest przestarzały.

Żądanie

POST /api/rank_tracker/reports/ai_overviews/getAioSources

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "project_id": null,
  "keyword_id": null
}

Rozszerzony

żądanie-rozszerzone.jsonc


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

cURL


curl --location --request POST 'https://api.senuto.com/api/rank_tracker/reports/ai_overviews/getAioSources' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "project_id": null, "keyword_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`.
`keyword_id`	`number` Wymagane. ID frazy w projekcie (kontrola dostępu `KeywordAccessRules` — fraza musi należeć do podanego `project_id`). Brak `keyword_id` → `418` z `invalid_data`. ID fraz pobierzesz np. z `getGroupKeywords` / `getProjectKeywords` w kontrolerze Keywords.
`limit`	`number` Rozmiar strony paginacji. Odbija się w `pagination.limit`.	`10`
`page`	`number` Numer strony paginacji.	`1`

Ten endpoint nie obsługuje filtering ani order — wbrew wcześniejszej wersji tej strony. Endpoint w ogóle nie odczytuje tych parametrów, a na prod nieznany klucz w filtering nie zwraca 418 (jest po cichu ignorowany, 200). Filtrowanie/sortowanie zastosuj po stronie klienta. (Uwaga: inne raporty modułu AI Overviews — np. getKeywords, getOpportunities, getCompetitors — filtrowanie obsługują; ten konkretny endpoint nie.)

Blok AI Overview może istnieć dla frazy, a lista źródeł i tak wrócić pusta — data: [] przy page_count: 1. Traktuj pustą listę jako poprawną odpowiedź, nie błąd.

Odpowiedź

Po pomyślnym żądaniu otrzymujesz standardową kopertę: success, data (tablica źródeł cytowanych w bloku AIO) oraz pagination. Dla frazy bez cytowanych źródeł tablica data jest pusta przy count: 0 — zwróć uwagę, że w tym przypadku page_count wyniosło 1 (inaczej niż 0 w getKeywords/getOpportunities przy braku danych).

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [],
  "pagination": { "page_count": 1, "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[]` Źródła cytowane w bloku AI Overview danej frazy. Kształt wiersza zależy od źródeł cytowanych w bloku AI Overview danej frazy.
`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 keyword_id → invalid_data; cudzy lub nieistniejący project_id → Unauthorized access (ProjectAccessRules); keyword_id nienależący do podanego projektu jest odrzucany przez KeywordAccessRules — 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 — frazy z AIO, w których domena rankuje organicznie, ale nie jest cytowana
getAioDetails — pełny surowy blok AI Overview danej frazy (project_id + keyword_id)
getAioSources — źródła cytowane w bloku AIO frazy (ta strona)

AI Overviews: źródła (getAioSources)