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

# Szczegóły frazy: liderzy tematu (`getTopicLeaders`)

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

Zwraca **adresy URL, które najczęściej rankują w TOP** dla fraz z tematu wokół podanego słowa kluczowego. `occurrences` mówi, dla ilu fraz z tematu dany URL się pojawia — czyli kto dominuje cały temat, a nie jedną 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ń.

Dla frazy `hamak` w Polsce raport zwrócił **23528** wierszy.

---

## Żądanie

`POST` `/api/keywords_analysis/reports/keyword_details/getTopicLeaders`

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/getTopicLeaders' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{"keyword":"hamak","country_id":1,"limit":10}'
```

### Parametry

```ts
type KeywordDetailsGetTopicLeadersRequest = {
/** **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;
/**
 * Filtry raportu — tablica grup łączonych operatorem OR. **Działa na tej akcji.**
 * Nieznany `key` zwraca `418` z `invalid_filtering`. Opis mechanizmu: /types/filter
 */
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 KeywordDetailsGetTopicLeadersRequest
```

> **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:**
> Metryki są **zdublowane w trzech miejscach**: pola najwyższego poziomu (`searches`, `cpc`, `trends`), płaskie `trend_1` … `trend_12` oraz obiekt `statistics`. Do integracji wybierz jedno źródło — `statistics` różni się tylko tym, że jego lista cech SERP jest bez duplikatów.

## 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": [
    {
      "url": "leroymerlin.pl/relaks-w-ogrodzie/hustawki-ogrodowe-hamaki,a47.html",
      "occurrences": 774
    }
  ],
  "pagination": {
    "page_count": 11764,
    "current_page": 1,
    "has_next_page": true,
    "has_prev_page": false,
    "count": 23528,
    "limit": 2
  }
}
```

### Struktura odpowiedzi

```ts
type KeywordDetailsGetTopicLeadersResponse = {
success: boolean;
data: Array<{
  /** Adres URL — bez schematu w części wyników. */
  url: string;
  /** Liczba fraz z tematu, dla których ten URL rankuje w TOP. */
  occurrences: number;
}>;
/** Paginacja liczona z całego zbioru — `count` to liczba wszystkich wierszy. */
pagination: {
  page_count: number; current_page: number;
  has_next_page: boolean; has_prev_page: boolean;
  count: number; limit: number;
};
}
export default KeywordDetailsGetTopicLeadersResponse
```

## 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.
- [`getGroups`](/modules/keywords_analysis/ka-keyword-details-getGroups) — grupy frazy.
- [`getCompetitorsNumber`](/modules/keywords_analysis/ka-keyword-details-getCompetitorsNumber) — liczba konkurentów.