---
title: "Baza słów kluczowych: grupy zbioru (`getGroups`)"
source: https://docs.senuto.com/modules/keywords_analysis/ka-keywords-getGroups
api: POST /api/keywords_analysis/reports/keywords/getGroups
---

# Baza słów kluczowych: grupy zbioru (`getGroups`)

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

Zwraca **zbiór fraz pogrupowany tematycznie** — każdy wiersz to grupa ze wspólnym fragmentem frazy, wraz z liczbą fraz i sumami oraz średnimi wyszukiwań i CPC. Pozwala zobaczyć strukturę dużego zbioru, zanim zejdziesz do pojedynczych fraz.

---

## Żądanie

`POST` `/api/keywords_analysis/reports/keywords/getGroups`

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

**Żądanie**

```jsonc filename="żądanie.jsonc"
{
  "parameters": [
    {
      "data_fetch_mode": "keyword",
      "value": [
        "buty do biegania"
      ]
    }
  ],
  "match_mode": "wide",
  "country_id": 1,
  "limit": 3
}
```

**cURL**

```bash
curl --location --request POST 'https://api.senuto.com/api/keywords_analysis/reports/keywords/getGroups' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{"parameters": [{"data_fetch_mode": "keyword", "value": ["buty do biegania"]}], "match_mode": "wide", "country_id": 1, "limit": 3}'
```

### Parametry

```ts
type KeywordsGetGroupsRequest = {
/**
 * **Wymagane**. Zapytanie do bazy: lista obiektów `{ data_fetch_mode, value }`.
 * Tryb `keyword` przyjmuje listę fraz w `value`.
 */
parameters: Array<{ data_fetch_mode: 'keyword' | string; value: string[] }>;
/** **Wymagane**. Szerokość dopasowania frazy: `wide` | `medium` | `narrow`. */
match_mode: 'wide' | 'medium' | 'narrow';
/** **Wymagane**. Identyfikator kraju; nieznana wartość zwraca `418` z `Unknown country_id`. */
country_id: number;
/** Filtry — tablica grup łączonych OR. Nieznany `key` zwraca `418` z `invalid_filtering`. */
filtering?: Array<{
  filters: Array<{ key: string; match?: 'gt' | 'gte' | 'lt' | 'lte' | 'eq'; value: string | number | Array<string | number> }>;
  conjunction?: 'and' | 'or';
}>;
/** Numer strony wyników. */
page?: number;
/** Liczba wierszy na stronę. */
limit?: number;
}
export default KeywordsGetGroupsRequest
```

> **Ostrzeżenie:**
> Liczba pobieranych wierszy podlega limitowi `keywords_analysis_rows_per_report` — przy zbyt dużym `limit` albo wysokim `page` żądanie zwróci `418` z informacją o przekroczeniu limitu.

> **Ostrzeżenie:**
> Paginacja jest **rzeczywista**: dla frazy `buty do biegania` w Polsce raport zwrócił `count: 23239` grup. To inny endpoint niż [`keyword_details/getGroups`](/modules/keywords_analysis/ka-keyword-details-getGroups), którego paginacja jest pozorna.

## Odpowiedź

Przykład to **rzeczywista odpowiedź produkcyjna**, skrócona.

```json filename="przykładowa-odpowiedź"
{
  "success": true,
  "data": [
    {
      "group": "do biegania",
      "keywords_sum": 2902,
      "searches_sum": 461430,
      "searches_avg": 159,
      "cpc_sum": 1536.35,
      "cpc_avg": 0.53
    },
    {
      "group": "buty do",
      "keywords_sum": 2391,
      "searches_sum": 413430,
      "searches_avg": 172.91,
      "cpc_sum": 1244.23,
      "cpc_avg": 0.52
    }
  ],
  "pagination": {
    "page_count": 7747,
    "current_page": 1,
    "has_next_page": true,
    "has_prev_page": false,
    "count": 23239,
    "limit": 3
  }
}
```

### Struktura odpowiedzi

```ts
type KeywordsGetGroupsResponse = {
success: boolean;
data: Array<{
  /** Nazwa grupy — wspólny fragment fraz. */
  group: string;
  /** Liczba fraz w grupie. */
  keywords_sum: number;
  /** Suma wyszukiwań fraz w grupie. */
  searches_sum: number;
  /** Średnia liczba wyszukiwań w grupie. */
  searches_avg: number;
  /** Suma CPC fraz w grupie. */
  cpc_sum: number;
  /** Średni CPC w grupie. */
  cpc_avg: number;
}>;
pagination: {
  page_count: number; current_page: number;
  has_next_page: boolean; has_prev_page: boolean;
  count: number; limit: number;
};
}
export default KeywordsGetGroupsResponse
```

## Błędy

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

## Powiązane akcje

- [`getKeywords`](/modules/keywords_analysis/ka-keywords-getKeywords) — frazy ze zbioru.
- [`getGroupKeywords`](/modules/keywords_analysis/ka-keywords-getGroupKeywords) — frazy w obrębie grupy.
- [`keyword_details/getGroups`](/modules/keywords_analysis/ka-keyword-details-getGroups) — grupy dla **jednej** frazy.