---
title: "Frazy: przypisania grup (`getData`)"
source: https://docs.senuto.com/modules/rank_tracker/rt-keywords-getData
api: POST /api/rank_tracker/reports/keywords/getData
---

# Frazy: przypisania grup (`getData`)

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

Zwraca listę fraz projektu Rank Tracker wraz z informacją o ich przynależności do grup. Każdy element zawiera `id` frazy, jej nazwę (`keyword`) oraz przypisane grupy w dwóch formach: `keyword_groups` (string) i `groups` (tablica). Endpoint **nie zwraca statystyk pozycji** — te udostępnia akcja `getData` kontrolera `positions` (`/api/rank_tracker/reports/positions/getData`). Wynik jest stronicowany.

| Fraza | ID | Grupy (string) | Grupy (tablica) |
| --- | --- | --- | --- |
| kiedy pierwsza cieczka u psa | 8301076 | piesek | ["piesek"] |
| jak wozic psa w aucie | 19940324 | piesek | ["piesek"] |

_projekt i grupa Rank Trackera, limit: 2. Zwróć uwagę: id frazy to string, a te same nazwy grup zwracane są w dwóch formach — keyword_groups (string) i groups (tablica). Wszystkie adresowalne pola wiersza._

---

## Żądanie

`POST` `/api/rank_tracker/reports/keywords/getData`

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

### Struktura żądania

**Podstawowy**

```jsonc filename="żądanie-podstawowe.jsonc"
// bez group_id — wszystkie frazy projektu
{
  "project_id": null,
  "limit": 2
}
```

**Rozszerzony**

```jsonc filename="żądanie-rozszerzone.jsonc"
// z group_id — tylko frazy wskazanej grupy
{
  "project_id": null,
  "group_id": null,
  "limit": 2
}
```

**cURL**

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

### Parametry

```ts
type GetKeywordsDataRequest = {
/**
 * **Wymagane**. ID projektu Rank Tracker — jedyne pole twardo wymagane przez walidator (`GroupKeywordsValidator`).
 * Musi należeć do użytkownika, inaczej zwracane jest `418` z `Unauthorized access`.
 * Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
 */
project_id: number;
/**
 * Opcjonalne. ID grupy słów kluczowych. Bez tego pola endpoint zwraca **wszystkie** frazy projektu
 * (zwalidowane: `count: "94"`); z nim — tylko frazy wskazanej grupy (zwalidowane: `count: "62"`).
 */
group_id?: number;
/**
 * Rozmiar strony paginacji. Odbija się w `pagination.limit`.
 * @default 10
 */
limit?: number;
/**
 * Numer strony paginacji.
 * @default 1
 */
page?: number;
}
export default GetKeywordsDataRequest
```

> **Błąd:**
> **`filtering` działa tylko dla pola `keyword`.** Filtr po `keyword` zawęża wynik poprawnie,
> ale filtr po `groups` — mimo że to pole jest w odpowiedzi — kończy się `500`. Nieznany klucz
> również zwraca `500`, a nie `418`. Puste `filtering` (`[]` albo grupa bez warunków) jest
> bezpieczne i nie zmienia wyniku.

> **Ostrzeżenie:**
> **`order` nie ma efektu na tej akcji** — `dir: "ASC"` i `"DESC"` zwracają wynik w tej samej,
> domyślnej kolejności. Sortuj po swojej stronie.

> **Ostrzeżenie:**
> **Pułapki potwierdzone na produkcji:**
>
> - `id` frazy oraz `pagination.count` są zwracane jako **stringi** (`"8301076"`, `"94"`) — w odróżnieniu od pozostałych pól paginacji, które są liczbami. Rzutuj je po swojej stronie.
> - `keyword_groups` to **jeden string** z nazwami grup rozdzielonymi znakiem **nowej linii** (`\n`), np. `"szcze\nBez grupy"`. Pole `groups` zawiera tę samą informację jako tablicę — używaj `groups`, jeśli nie chcesz parsować stringa.
> - `group_id` jest **opcjonalne**: bez niego endpoint zwraca **wszystkie** frazy projektu (`count` podaje ich łączną liczbę), a z nim zawęża wynik do fraz wskazanej grupy (`count: "62"`).

## Odpowiedź

Po pomyślnym żądaniu otrzymujesz `data` (tablicę fraz z przypisaniami grup) oraz `pagination`. Zwróć uwagę na typy: `id` frazy i `pagination.count` to stringi, a `keyword_groups` to string wieloliniowy (separator `\n`) — jego tablicowym odpowiednikiem jest `groups`.

**Skrócona**

```json filename="przykładowa-odpowiedź (skrócona, z group_id)"
{
  "success": true,
  "data": [
    { "id": "8301076", "keyword": "kiedy pierwsza cieczka u psa", "keyword_groups": "piesek", "groups": ["piesek"] }
  ],
  "pagination": { "page_count": 31, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": "62", "limit": 2 }
}
```

**Pełna**

```json filename="przykładowa-odpowiedź (zwalidowana, 200, bez group_id)"
{
  "success": true,
  "data": [
    {
      "id": "1053348",
      "keyword": "owczarek szkocki",
      "keyword_groups": "szcze\nBez grupy",
      "groups": ["szcze", "Bez grupy"]
    },
    {
      "id": "8290613",
      "keyword": "cieczka u psa co ile",
      "keyword_groups": "szcze\nBez grupy",
      "groups": ["szcze", "Bez grupy"]
    }
  ],
  "pagination": {
    "page_count": 47,
    "current_page": 1,
    "has_next_page": true,
    "has_prev_page": false,
    "count": "94",
    "limit": 2
  }
}
```

### Struktura odpowiedzi

```ts
type GetKeywordsDataResponse = {
/** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */
success: boolean;
/** Frazy projektu (lub grupy, jeśli podano `group_id`) z przypisaniami grup */
data: KeywordWithGroups[];
/** Metadane paginacji */
pagination: {
  page_count: number;
  current_page: number;
  has_next_page: boolean;
  has_prev_page: boolean;
  /** **Uwaga:** string, nie liczba (np. `"94"`) */
  count: string;
  limit: number;
};
}

type KeywordWithGroups = {
/** ID frazy — **uwaga:** string, nie liczba (np. `"8301076"`) */
id: string;
/** Nazwa frazy */
keyword: string;
/** Nazwy grup jako jeden string rozdzielony znakiem nowej linii (`\n`), np. `"szcze\nBez grupy"` */
keyword_groups: string;
/** Te same nazwy grup jako tablica — preferowana forma do przetwarzania */
groups: string[];
}
export default GetKeywordsDataResponse
```

## 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 przy błędach walidacji (`invalid_data`) — nie tylko przy ograniczaniu liczby żądań. Brak `project_id` → `418` z `{"project_id":{"_required":"This field is required"}}`. Cudzy lub nieistniejący `project_id` zwraca `418` z `Unauthorized access`, a nie `404`.

## Powiązane akcje

- `getData` — frazy projektu z przypisaniami grup, bez statystyk pozycji (ta strona)
- `getProjectKeywords` — słowa kluczowe całego projektu
- `getGroupKeywords` — lekka lista (`id` + `keyword`) ograniczona do jednej grupy
- `getSerpHtml` — zapis HTML wyników SERP
- `getBestKeywords` / `getProjectsStatus` — pozostałe akcje pomocnicze kontrolera