---
title: "Frazy: słowa kluczowe grupy (`getGroupKeywords`)"
source: https://docs.senuto.com/modules/rank_tracker/rt-keywords-getGroupKeywords
api: POST /api/rank_tracker/reports/keywords/getGroupKeywords
---

# Frazy: słowa kluczowe grupy (`getGroupKeywords`)

**`POST /api/rank_tracker/reports/keywords/getGroupKeywords`**

Zwraca lekką listę słów kluczowych należących do wskazanej grupy w projekcie Rank Tracker. Każdy element to wyłącznie `id` słowa kluczowego oraz jego nazwa (`keyword`) — bez danych o pozycjach czy statystykach (te udostępnia osobna akcja, np. `getData` w tym samym kontrolerze). Wynik jest stronicowany.

| Fraza | ID |
| --- | --- |
| jak wychować szczeniaka | 690709 |
| karma dla szczeniaka maltańczyka | 704922 |

_projekt i grupa Rank Trackera, limit: 2, strona 2. Każdy wiersz to wyłącznie para id + keyword. Wszystkie adresowalne pola wiersza._

---

## Żądanie

`POST` `/api/rank_tracker/reports/keywords/getGroupKeywords`

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

### Struktura żądania

**Podstawowy**

```jsonc filename="żądanie-podstawowe.jsonc"
{
  "project_id": null,
  "group_id": null
}
```

**Rozszerzony**

```jsonc filename="żądanie-rozszerzone.jsonc"
{
  "project_id": null,
  "group_id": null,
  "limit": 2,
  "page": 2
}
```

**cURL**

```bash
curl --location --request POST 'https://api.senuto.com/api/rank_tracker/reports/keywords/getGroupKeywords' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "project_id": null, "group_id": null, "limit": 2, "page": 2 }'
```

### Parametry

```ts
type GetGroupKeywordsRequest = {
/**
 * **Wymagane**. ID projektu Rank Tracker. Jedyne pole twardo wymagane przez walidator (`ProjectAccessRules::requirePresence`).
 * Musi należeć do użytkownika (lub być udostępnione przez `AclUsersRoles`), inaczej zwracane jest `Unauthorized access`.
 * Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
 */
project_id: number;
/**
 * **Wymagane**. ID grupy słów kluczowych w projekcie. Formalnie nie jest wymuszane przez `requirePresence`,
 * ale bez niego zapytanie filtruje po `group_id = null` i zwraca pustą listę (`data: []`, `count: 0`) z `HTTP 200` —
 * więc funkcjonalnie jest wymagane. Listę grup pobierzesz z `GET /api/rank_tracker/management/groups/list?project_id=<id>`.
 * `group_id` musi należeć do podanego `project_id`, inaczej zwracane jest `Unauthorized access`.
 */
group_id: number;
/**
 * Rozmiar strony paginacji (nieujemna liczba całkowita, `maxLimit = 100`). Odbija się w `pagination.limit`.
 * @default 10
 */
limit?: number;
/**
 * Numer strony paginacji (nieujemna liczba całkowita).
 * @default 1
 */
page?: number;
}
export default GetGroupKeywordsRequest
```

> **Ostrzeżenie:**
> Choć `group_id` nie jest wymuszane przez walidator (`requirePresence` działa dla niego warunkowo — tylko gdy pole już jest w danych), w praktyce zawsze je podawaj: bez `group_id` otrzymasz `HTTP 200` z pustą listą, a nie błąd. Podanie `group_id` nienależącego do `project_id` skutkuje `Unauthorized access`.

> **Ostrzeżenie:**
> Endpoint obsługuje wyłącznie metodę **`POST`** — parametry przekazuj w **ciele żądania** (`getData()` czyta `body` zarówno w walidatorze, jak i w warunku `WHERE GroupsKeywords.group_id`). **Pułapka:** ten sam URL wywołany przez `GET` zwraca `HTTP 200`, ale **zawsze** `data: []` i `count: 0` — nawet z poprawnym `project_id`/`group_id` w query stringu — ponieważ przy `GET` ciało jest puste, a filtr leci po `group_id = null`. Twardo wymagane jest tylko **`project_id`**; brak **`group_id`** nie powoduje błędu walidacji, lecz zwraca pustą listę z `HTTP 200`, więc funkcjonalnie `group_id` jest również wymagane. Brak `project_id` → `418` z `invalid_data`.

## Odpowiedź

Po pomyślnym żądaniu otrzymujesz `data` (tablicę słów kluczowych grupy) oraz `pagination`. Każdy element `data` zawiera wyłącznie `id` (liczba całkowita) i `keyword` (nazwa frazy). `count` w `pagination` odzwierciedla rzeczywistą liczbę słów kluczowych w grupie.

**Skrócona**

```json filename="przykładowa-odpowiedź (skrócona)"
{
  "success": true,
  "data": [
    { "id": 690709, "keyword": "jak wychować szczeniaka" }
  ],
  "pagination": { "page_count": 31, "current_page": 2, "has_next_page": true, "has_prev_page": true, "count": 62, "limit": 2 }
}
```

**Pełna**

```json filename="przykładowa-odpowiedź (200)"
{
  "success": true,
  "data": [
    {
      "id": 690709,
      "keyword": "jak wychować szczeniaka"
    },
    {
      "id": 704922,
      "keyword": "karma dla szczeniaka maltańczyka"
    }
  ],
  "pagination": {
    "page_count": 31,
    "current_page": 2,
    "has_next_page": true,
    "has_prev_page": true,
    "count": 62,
    "limit": 2
  }
}
```

### Struktura odpowiedzi

```ts
type GetGroupKeywordsResponse = {
/** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */
success: boolean;
/** Słowa kluczowe należące do grupy */
data: GroupKeyword[];
/** Metadane paginacji */
pagination: {
  page_count: number;
  current_page: number;
  has_next_page: boolean;
  has_prev_page: boolean;
  count: number;
  /** Wartość przekazanego `limit`; `null`, gdy nie podano */
  limit: number | null;
};
}

type GroupKeyword = {
/** ID słowa kluczowego */
id: number;
/** Nazwa frazy */
keyword: string;
}
export default GetGroupKeywordsResponse
```

## Błędy

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

> **Błąd:**
> **`418`** jest zwracane również w przypadku błędów walidacji — nie tylko przy ograniczaniu liczby żądań. Brak `project_id` →
> `{"success":false,"data":{"error":{"type":"invalid_data","params":{"project_id":{"_required":"This field is required"},"group_id":{"unauthorized":"Unauthorized access"}}}}}`
> (bez `project_id` nie da się potwierdzić dostępu do grupy). Cudzy lub nieistniejący `project_id` / `group_id` zwraca `Unauthorized access` (`418`), a nie `404`. Konto administratora (`role_id = 1`) omija obie kontrole dostępu.

## Powiązane akcje

- `getGroupKeywords` — lekka lista (`id` + `keyword`) ograniczona do jednej grupy (ta strona)
- `getProjectKeywords` — słowa kluczowe całego projektu (`POST`, `project_id`, bez `group_id`)
- `getData` — pełne statystyki pozycji (`POST`, `project_id` + `group_id` + `filtering` + `order`)
- `getSerpHtml` — zapis HTML wyników SERP (`POST`, `keyword_id` + `date` + `project_id`)
- `getBestKeywords` / `getProjectsStatus` — pozostałe akcje pomocnicze kontrolera