---
title: "Sekcje i URL-e: subdomeny (`getSubdomains`)"
source: https://docs.senuto.com/modules/visibility_analysis/va-sections-getSubdomains
api: POST /api/visibility_analysis/reports/sections/getSubdomains
---

# Sekcje i URL-e: subdomeny (`getSubdomains`)

**`POST /api/visibility_analysis/reports/sections/getSubdomains`**

Zwraca widoczność domeny w rozbiciu na subdomeny. Każdy wiersz odpowiada jednej subdomenie (pole `domain` zawiera jej nazwę) i obok statystyk `visibility`, `top3`, `top10` i `top50` zawiera **dodatkowo** `visibility_coverage` — pokrycie widoczności całej domeny przez daną subdomenę. Użyj tej akcji, aby sprawdzić, jak widoczność rozkłada się między subdomeny serwisu.

| Domena | Frazy | Udział wid. % | Widoczność | Widoczność poprz. | Widoczność Δ | Widoczność % | TOP3 | TOP3 poprz. | TOP3 Δ | TOP3 % | TOP10 | TOP10 poprz. | TOP10 Δ | TOP10 % | TOP50 | TOP50 poprz. | TOP50 Δ | TOP50 % | Pokrycie wid. | Pokrycie wid. poprz. | Pokrycie wid. Δ | Pokrycie wid. % |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| zalando.pl | 114658 | 100 | 5434165.18 | 5380498.4 | 53666.78 | 0.01 | 46869 | 46517 | 352 | 0.0076 | 114658 | 114147 | 511 | 0.0045 | 288521 | 288895 | -374 | -0.0013 | 100 | 100 | 0 | 0 |

_zalando.pl — domena nie ma innych subdomen, stąd jeden wiersz z pełnym pokryciem widoczności. Wszystkie pola wiersza (poza mapami historii `statistics.*.history` o kluczach-datach — są w JSON; w tej odpowiedzi mają wartość null)._

---

## Żądanie

`POST` `/api/visibility_analysis/reports/sections/getSubdomains`

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

### Struktura żądania

**Podstawowy**

```jsonc filename="żądanie-podstawowe.jsonc"
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1
}
```

**Rozszerzony**

```jsonc filename="żądanie-rozszerzone.jsonc"
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1,
  "limit": 2,
  "page": 1
}
```

**cURL**

```bash
curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/sections/getSubdomains' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{
    "domain": "zalando.pl",
    "fetch_mode": "topLevelDomain",
    "country_id": 1,
    "limit": 2
  }'
```

### Parametry

```ts
type SectionsGetSubdomainsRequest = {
/**
 * **Wymagane**. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`.
 */
domain: string;
/**
 * **Wymagane**. Sposób interpretacji `domain`.
 * - `topLevelDomain` — cała domena
 * - `subdomain` — pojedyncza subdomena
 * - `catalog` — ścieżka/katalog
 * - `url` — dokładny URL
 *
 * Wartość `"domain"` nie istnieje — użyj `topLevelDomain`.
 */
fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url';
/**
 * **Wymagane**. Id kraju (bazy danych). Polska = `1`. Nieznana wartość zwraca `418` z komunikatem `Unknown country_id`.
 */
country_id: number;
/**
 * Liczba wierszy na stronę.
 * @default 10
 */
limit?: number;
/**
 * Numer strony.
 * @default 1
 */
page?: number;
}
export default SectionsGetSubdomainsRequest
```

> **Ostrzeżenie:**
> Ten endpoint **nie obsługuje** parametrów `order` ani `filtering`. Jeśli je wyślesz, API zwróci `200`, ale zostaną **zignorowane** — wyniki wracają w kolejności domyślnej. Zweryfikowane na prod — endpoint ich nie odczytuje. W przeciwieństwie do raportu `positions`, sekcje nie mają sortowania ani filtrowania po stronie API — jedyne parametry sterujące to `limit` i `page`.

> **Ostrzeżenie:**
> Trzy parametry są **wymagane** (walidator `SectionsValidator`): **`domain`**, **`fetch_mode`** oraz **`country_id`**. Dozwolone wartości `fetch_mode` to `topLevelDomain`, `subdomain`, `catalog` i `url` — wartość `"domain"` **nie istnieje**. Nieznane `country_id` zwraca `418` z komunikatem `"Unknown country_id"`.

## Odpowiedź

W przypadku powodzenia otrzymujesz `data` (tablicę subdomen) oraz `pagination`. Dla `zalando.pl` API zwróciło jeden wiersz — domena nie ma innych subdomen, stąd `visibility_percent` i `visibility_coverage` wynoszą `100`.

**Skrócona**

```json filename="przykładowa-odpowiedź (skrócona)"
{
  "success": true,
  "data": [
    { "domain": "zalando.pl", "keywords_count": 114658, "visibility_percent": 100, "statistics": { "visibility": { "current": 5434165.18 }, "visibility_coverage": { "current": 100 } /* … */ } }
  ],
  "pagination": { "page_count": 1, "current_page": 1, "has_next_page": false, "has_prev_page": false, "count": 1, "limit": 2 }
}
```

**Pełna**

```json filename="przykładowa-odpowiedź (200)"
{
  "success": true,
  "data": [
    {
      "domain": "zalando.pl",
      "keywords_count": 114658,
      "visibility_percent": 100,
      "statistics": {
        "visibility": { "current": 5434165.18, "previous": 5380498.4, "diff": 53666.78, "percent": 0.01, "history": null },
        "top3": { "current": 46869, "previous": 46517, "diff": 352, "percent": 0.0076, "history": null },
        "top10": { "current": 114658, "previous": 114147, "diff": 511, "percent": 0.0045, "history": null },
        "top50": { "current": 288521, "previous": 288895, "diff": -374, "percent": -0.0013, "history": null },
        "visibility_coverage": { "current": 100, "previous": 100, "diff": 0, "percent": 0, "history": null }
      }
    }
  ],
  "pagination": { "page_count": 1, "current_page": 1, "has_next_page": false, "has_prev_page": false, "count": 1, "limit": 2 }
}
```

### Struktura odpowiedzi

```ts
type SectionsGetSubdomainsResponse = {
/** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */
success: boolean;
/** Zwrócone wiersze z subdomenami */
data: SubdomainRow[];
/** Metadane paginacji */
pagination: {
  page_count: number;
  current_page: number;
  has_next_page: boolean;
  has_prev_page: boolean;
  count: number;
  limit: number;
};
}

type SubdomainRow = {
/** Nazwa subdomeny, np. "zalando.pl" */
domain: string;
/** Liczba fraz w TOP10 przypisanych do subdomeny */
keywords_count: number;
/** Procentowy udział subdomeny w widoczności domeny */
visibility_percent: number;
statistics: {
  visibility: StatEntry;
  top3: StatEntry;
  top10: StatEntry;
  top50: StatEntry;
  /** Pokrycie widoczności domeny przez subdomenę (tylko w tej akcji) */
  visibility_coverage: StatEntry;
};
}

type StatEntry = {
current: number;
previous: number;
diff: number;
percent: number;
history: null;
}
export default SectionsGetSubdomainsResponse
```

## Błędy

```ts
type ErrorResponse = {
success: false;
data: {
  error: {
    /** np. invalid_data, database, timeout, unknown */
    type: string;
    message: string;
    /** pole -> reguła -> komunikat (dla invalid_data) */
    params?: Record<string, Record<string, string>>;
  };
};
}
export default ErrorResponse
```

> **Błąd:**
> **`418`** zwracany jest również dla błędów walidacji — nie tylko przy ograniczeniu liczby żądań (rate limiting). Brak wymaganego pola zwraca `invalid_data` z mapą `params`, a nieznane `country_id` zwraca komunikat `"Unknown country_id"`.

## Powiązane akcje

- [`getSections`](/modules/visibility_analysis/va-sections-getSections) — widoczność zagregowana po sekcjach URL (katalogach) domeny
- `getSubdomains` — widoczność per subdomena (ta strona)
- [`getUrls`](/modules/visibility_analysis/va-sections-getUrls) — widoczność per pojedynczy adres URL