AI Overviews: szczegóły AIO (`getAioDetails`)

POST/api/rank_tracker/reports/ai_overviews/getAioDetails

Zwraca surową treść bloku AI Overview (AIO) dla wskazanej frazy projektu Rank Tracker: pełny tekst bloku (text), status pobrania (status), pozycję bloku w SERP (rank_absolute), listę źródeł (sources[]) oraz linki osadzone w treści (content_links[] z polami url, text, rank_inner). Wynikiem jest pojedynczy obiekt — bez paginacji. Ten raport — w odróżnieniu od modułu AI Overviews w Analizie widoczności — nie jest przestarzały.

Żądanie

POST /api/rank_tracker/reports/ai_overviews/getAioDetails

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
}

cURL


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

Parametry

Name	Type	Default
`project_id`	`number` Wymagane. ID projektu Rank Tracker (`ProjectAccessRules`). Projekt musi należeć do użytkownika lub być mu udostępniony — cudzy `project_id` zwraca `418` z `Unauthorized access`. Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
`keyword_id`	`number` Wymagane przez `AioDetailsValidator`. ID frazy w projekcie — fraza musi należeć do podanego `project_id` (`KeywordAccessRules`). Brak `keyword_id` zwraca `418` z `invalid_data` i regułą `_required`. ID frazy pobierzesz np. z `POST /api/rank_tracker/reports/keywords/getGroupKeywords`.

Walidator AioDetailsValidator wymaga project_id i keyword_id — brak keyword_id zwraca 418 z invalid_data i regułą _required. keyword_id musi należeć do podanego projektu (KeywordAccessRules), a cudzy project_id zwraca 418 z Unauthorized access. Pułapki: w zwalidowanej odpowiedzi sources[] jest puste, mimo że content_links[] są wypełnione — nie zakładaj, że oba pola są uzupełniane razem. Treść bloku AIO pochodzi wprost z SERP i może być w innym języku niż projekt — w przykładzie poniżej Google zwrócił blok po czesku dla frazy zawierającej słowo „jak”.

Odpowiedź

Po pomyślnym żądaniu otrzymujesz w data pojedynczy obiekt (bez paginacji) z pełnym tekstem bloku AIO, statusem, pozycją bloku w SERP oraz listami źródeł i linków osadzonych w treści. Pamiętaj, że treść bloku odzwierciedla to, co faktycznie wyświetlił Google — może więc być w innym języku niż projekt.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": {
    "text": "• Zvíře: Dlouhosrstý tur žijící ve velehorách Střední Asie (více na Wikipedii). …",
    "status": "success",
    "rank_absolute": 1,
    "sources": [],
    "content_links": [
      { "url": "https://cs.wikipedia.org/wiki/Jak_divok%C3%BD", "text": "Wikipedii", "rank_inner": 1 }
    ]
  }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`AioDetails` Szczegóły bloku AI Overview dla frazy — pojedynczy obiekt, bez paginacji

Błędy

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

418 jest zwracane również przy błędach walidacji i dostępu. Brak keyword_id skutkuje invalid_data z regułą _required (walidator AioDetailsValidator). Cudzy lub nieistniejący project_id zwraca Unauthorized access (418), a nie 404; keyword_id nienależący do projektu również nie przejdzie kontroli KeywordAccessRules.

Powiązane akcje

getStatistics — zbiorcze metryki aio_* domeny projektu (z historią)
getKeywords — frazy projektu z obecnością w AI Overviews
getDistribution — rozkład obecności w blokach AIO
getCompetitors — porównanie obecności w AIO z konkurentami
getOpportunities — frazy z szansą na obecność w AIO
getAioDetails — surowa treść bloku AIO dla pojedynczej frazy (ta strona)
getAioSources — źródła cytowane w blokach AIO

AI Overviews: szczegóły AIO (getAioDetails)