---
title: "Szczegóły frazy: grupy frazy (`getGroups`)"
source: https://docs.senuto.com/modules/keywords_analysis/ka-keyword-details-getGroups
api: POST /api/keywords_analysis/reports/keyword_details/getGroups
---

# Szczegóły frazy: grupy frazy (`getGroups`)

**`POST /api/keywords_analysis/reports/keyword_details/getGroups`**

Zwraca **grupy tematyczne** fraz powiązanych z podanym słowem kluczowym wraz z liczbą fraz w grupie (`keywords_sum`). Pozwala zobaczyć strukturę tematu, zanim zejdziesz do pojedynczych fraz.

Raport odpytujesz **wprost frazą i krajem** — bez wcześniejszego tworzenia zadania w Analizie
SERP. Jedno żądanie zastępuje ścieżkę „utwórz zadanie → sprawdź status → pobierz wynik"
i nie zużywa limitu zadań.

---

## Żądanie

`POST` `/api/keywords_analysis/reports/keyword_details/getGroups`

Nagłówki: `Authorization: Bearer <token>`, `Content-Type: application/json`.
Parametry przekazuje się w **treści żądania**.

**Żądanie**

```jsonc filename="żądanie.jsonc"
{
  "keyword": "hamak",
  "country_id": 1,
  "limit": 10
}
```

**cURL**

```bash
curl --location --request POST 'https://api.senuto.com/api/keywords_analysis/reports/keyword_details/getGroups' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{"keyword":"hamak","country_id":1,"limit":10}'
```

### Parametry

```ts
type KeywordDetailsGetGroupsRequest = {
/** **Wymagane**. Fraza kluczowa, dla której pobierany jest raport. Pusty string zwraca `418`. */
keyword: string;
/**
 * **Wymagane**. Identyfikator kraju; musi istnieć w słowniku krajów — nieznana wartość zwraca
 * `418` z komunikatem `Unknown country_id`. Uwaga: `200` jest tu mapowane na `1`.
 * @default 1
 */
country_id: number;
/**
 * **Ignorowane przez tę akcję.** Sprawdzone na produkcji: poprawny filtr nie zmienia liczby
 * wyników, a nieznany `key` zwraca `200` zamiast `418`. Filtruj po stronie klienta.
 */
filtering?: Array<Record<string, unknown>>;
/** Numer strony wyników. */
page?: number;
/** Liczba wierszy na stronę. */
limit?: number;
}
export default KeywordDetailsGetGroupsRequest
```

> **Ostrzeżenie:**
> Zarówno **`keyword`**, jak i **`country_id`** są **wymagane**. Nieznane `country_id` zwraca `418` z `Unknown country_id`, a wartość **`200` jest mapowana na `1`** — dla Polski trafisz więc do bazy 1.0, nie 2.0.

> **Ostrzeżenie:**
> Parametr **`filtering` nie działa na tej akcji.** Sprawdzone na produkcji: poprawny filtr nie zmienia liczby wyników, a nieznany klucz zwraca `200` zamiast `418`. Zawężaj wyniki po swojej stronie.

> **Ostrzeżenie:**
> **Paginacja jest pozorna.** Dla `limit` 1, 3, 10 i 100 API zwróciło odpowiednio 1, 3, 10 i 100 wierszy, a `count` zawsze równał się liczbie zwróconych wierszy przy `page_count: 1` i `has_next_page: false`. Nie stronicuj — pobierz całość jednym dużym `limit`.

## Odpowiedź

Przykład poniżej to **rzeczywista odpowiedź produkcyjna** dla frazy `hamak` (`country_id: 1`),
skrócona do jednego wiersza.

```json filename="przykładowa-odpowiedź"
{
  "success": true,
  "data": [
    {
      "group": "do hamaka",
      "keywords_sum": 234
    }
  ],
  "pagination": {
    "page_count": 1,
    "current_page": 1,
    "has_next_page": false,
    "has_prev_page": false,
    "count": 2,
    "limit": 2
  }
}
```

### Struktura odpowiedzi

```ts
type KeywordDetailsGetGroupsResponse = {
success: boolean;
data: Array<{
  /** Nazwa grupy — wspólny fragment fraz, np. `hamak ogrodowy`. */
  group: string;
  /** Liczba fraz przypisanych do grupy. */
  keywords_sum: number;
}>;
/**
 * **Paginacja pozorna.** `count` równa się liczbie zwróconych wierszy, `page_count` to zawsze
 * `1`, a `has_next_page` zawsze `false` — niezależnie od `limit`. Nie da się na tym
 * zbudować pętli stronicującej; pobierz całość jednym dużym `limit`.
 */
pagination: {
  page_count: number; current_page: number;
  has_next_page: boolean; has_prev_page: boolean;
  count: number; limit: number;
};
}
export default KeywordDetailsGetGroupsResponse
```

## Błędy

Błędy tego endpointu przychodzą we [wspólnej kopercie ze statusem `418`](/types/errors).

## Powiązane akcje

Wszystkie poniższe raporty przyjmują tę samą parę `keyword` + `country_id`:

- [`getStatistics`](/modules/keywords_analysis/ka-keyword-details-getStatistics) — zbiorcze statystyki frazy.
- [`getQuestions`](/modules/keywords_analysis/ka-keyword-details-getQuestions) — pytania o frazę.
- [`getKeywordsPropositions`](/modules/keywords_analysis/ka-keyword-details-getKeywordsPropositions) — propozycje fraz.
- [`getRelatedKeywords`](/modules/keywords_analysis/ka-keyword-details-getRelatedKeywords) — frazy powiązane.
- [`getTopicLeaders`](/modules/keywords_analysis/ka-keyword-details-getTopicLeaders) — liderzy tematu.
- [`getCompetitorsNumber`](/modules/keywords_analysis/ka-keyword-details-getCompetitorsNumber) — liczba konkurentów.