---
title: "AI Overviews: rozkład (`getDistribution`)"
source: https://docs.senuto.com/modules/visibility_analysis/va-ai-overviews-getDistribution
api: GET /api/visibility_analysis/reports/ai_overviews/getDistribution
---

# AI Overviews: rozkład (`getDistribution`)

**`GET /api/visibility_analysis/reports/ai_overviews/getDistribution`**

> **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ą.

Zwraca rozkład obecności domeny w blokach **AI Overviews (AIO)** Google dla wskazanej domeny. Raport pokazuje, jak słowa kluczowe wywołujące AI Overviews rozkładają się względem widoczności domeny w tych blokach — pozwala ocenić, w jakiej części zapytań wyzwalających AIO domena faktycznie pojawia się jako cytowane źródło.

---

## Żądanie

`GET` `/api/visibility_analysis/reports/ai_overviews/getDistribution`

Parametry są odczytywane z **query string** (`getQuery`). Nagłówki: `Authorization: Bearer <token>`.

### Struktura żądania

**Podstawowy**

```jsonc filename="żądanie-podstawowe.jsonc"
// Query string parameters
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain"
}
// GET /api/visibility_analysis/reports/ai_overviews/getDistribution?domain=zalando.pl&fetch_mode=topLevelDomain
```

**Rozszerzony**

```jsonc filename="żądanie-rozszerzone.jsonc"
// Query string parameters
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1
}
// GET /api/visibility_analysis/reports/ai_overviews/getDistribution?domain=zalando.pl&fetch_mode=topLevelDomain&country_id=1
```

**cURL**

```bash
curl --location --request GET 'https://api.senuto.com/api/visibility_analysis/reports/ai_overviews/getDistribution?domain=zalando.pl&fetch_mode=topLevelDomain' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE'
```

### Parametry

```ts
type AiOverviewsGetDistributionRequest = {
/**
 * **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 — gdy pominięte, `0` lub nieprawidłowe,
 * backend stosuje domyślny kraj (PL).
 * @default 1
 */
country_id?: number;
}
export default AiOverviewsGetDistributionRequest
```

> **Ostrzeżenie:**
> Dozwolone wartości `fetch_mode` to dokładnie `['topLevelDomain', 'subdomain', 'catalog', 'url']` (`DataFetchMode::AVAILABLE_MODES`). Przekazanie `domain` to częsty błąd — nie odpowiada żadnemu trybowi i nie przechodzi walidacji.

> **Ostrzeżenie:**
> Ta akcja jest wywoływana metodą **`GET`** i odczytuje dane z **query string**, więc parametry przesyłaj w adresie URL. Wysłanie żądania metodą `POST` zwraca `405`, a przesłanie parametrów wyłącznie w treści JSON kończy się `418`. Zarówno **`domain`**, jak i **`fetch_mode`** są **wymagane**. Wartość `fetch_mode` **`domain` nie istnieje** — dla całej domeny użyj **`topLevelDomain`**. Parametr `country_id` jest opcjonalny i domyślnie przyjmuje **PL (`1`)**, gdy jest pominięty lub nieprawidłowy.

> **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` oraz `data` — tablicę obiektów rozkładu obecności w AI Overviews. Gdy dla danej domeny brak danych AIO, `data` jest pustą tablicą (`[]`). 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": []
}
```

> **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 AiOverviewsDistributionResponse = {
/** Flaga przetworzenia żądania. Potwierdzone (`true`) w odpowiedzi `200`. */
success: boolean;
/**
 * Tablica obiektów rozkładu obecności w AI Overviews.
 * Pusta tablica (`[]`), gdy domena nie ma danych AIO.
 */
data: unknown[];
}
export default AiOverviewsDistributionResponse
```

## 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:**
> Wysłanie żądania niewłaściwą metodą **`POST`** zwraca **`405`** (Method Not Allowed) — ta akcja akceptuje wyłącznie `GET`. Z kolei **`418`** jest zwracane przy błędach walidacji (nie tylko przy ograniczaniu liczby żądań), m.in. gdy parametry trafią do treści JSON zamiast do query string (przez co `getQuery` jest puste) lub gdy pominięto `fetch_mode`. Brak `fetch_mode` →
> `{"success":false,"data":{"error":{"type":"invalid_data","params":{"fetch_mode":{"_required":"This field is required"}}}}}`.

## Powiązane akcje

- `getDistribution` — rozkład obecności domeny w AI Overviews (ta strona)
- `getStatistics` — zbiorcze statystyki AI Overviews dla domeny
- `getKeywords` — słowa kluczowe wywołujące AI Overviews (taki sam kształt żądania `domain` + `fetch_mode`)