---
title: "Lista konkurentów (`list`)"
source: https://docs.senuto.com/modules/rank_tracker/rt-competitors-list
api: GET /api/rank_tracker/management/competitors/list
---

# Lista konkurentów (`list`)

**`GET /api/rank_tracker/management/competitors/list`**

Zwraca listę konkurentów skonfigurowanych dla danego projektu Monitoringu (Rank Tracker). Konkurenci to domeny, które porównujesz z własnym projektem w raportach pozycji i widoczności. Odpowiedź zawiera tablicę `data` oraz metadane `pagination`.

---

## Żądanie

`GET` `/api/rank_tracker/management/competitors/list`

Nagłówki: `Authorization: Bearer <token>`. Parametry przekazywane w query stringu.

### Struktura żądania

**Podstawowy**

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

**Rozszerzony**

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

**cURL**

```bash
curl --location --request GET 'https://api.senuto.com/api/rank_tracker/management/competitors/list?project_id=124572' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE'
```

### Parametry

```ts
type CompetitorsListRequest = {
/**
 * **Wymagane**. Identyfikator projektu Monitoringu, dla którego zwracana jest lista konkurentów.
 * Przekazywany w query stringu (`?project_id=…`).
 * Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
 */
project_id: number;
/**
 * Liczba wierszy na stronę. Nieujemna liczba całkowita. Gdy pominięty, API może zwrócić wszystkie
 * wiersze (`limit: null`).
 */
limit?: number;
/**
 * Numer strony. Nieujemna liczba całkowita.
 * @default 1
 */
page?: number;
}
export default CompetitorsListRequest
```

> **Ostrzeżenie:**
> Endpoint obsługuje metodę **`GET`** — parametr **`project_id`** jest **wymagany** i przekazywany w **query stringu** (np. `?project_id=124572`), a nie w treści żądania. Wysłanie danych w body skutkuje odpowiedzią `418` / `405`.

> **Ostrzeżenie:**
> Przykładowy projekt nie zwrócił danych dla tego raportu (`data: []`) — nie miał skonfigurowanych konkurentów. Poniżej udokumentowano **strukturę** odpowiedzi i pojedynczego wiersza konkurenta na podstawie analizy schematu; nie zawiera ona zmyślonych wartości.

## Odpowiedź

Po pomyślnym żądaniu otrzymujesz `data` (tablicę konkurentów) oraz `pagination`. Jeśli projekt nie ma skonfigurowanych konkurentów, `data` jest pustą tablicą, a `pagination.count` wynosi `0`.

**Skrócona**

```json filename="przykładowa-odpowiedź (skrócona)"
{
  "success": true,
  "data": [],
  "pagination": { "count": 0, "current_page": 1, "page_count": 1 }
}
```

**Pełna**

```json filename="przykładowa-odpowiedź (200)"
{
  "success": true,
  "data": [],
  "pagination": {
    "page_count": 1,
    "current_page": 1,
    "has_next_page": false,
    "has_prev_page": false,
    "count": 0,
    "limit": null
  }
}
```

### Struktura odpowiedzi

```ts
type CompetitorsListResponse = {
/** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */
success: boolean;
/** Lista konkurentów projektu (pusta, gdy żaden nie został skonfigurowany) */
data: Competitor[];
/** Metadane paginacji */
pagination: {
  page_count: number;
  current_page: number;
  has_next_page: boolean;
  has_prev_page: boolean;
  /** Łączna liczba konkurentów */
  count: number;
  /** Limit wierszy na stronę; `null`, gdy nie ustawiono */
  limit: number | null;
};
}

// Struktura pojedynczego wiersza konkurenta (gdy `data` nie jest puste).
// Pola mogą się różnić w zależności od konfiguracji projektu.
type Competitor = {
/** Identyfikator konkurenta w obrębie projektu */
id: number;
/** Identyfikator projektu, do którego należy konkurent */
project_id: number;
/** Domena konkurenta */
domain: string;
}
export default CompetitorsListResponse
```

## Błędy

```ts
type ErrorResponse = {
success: false;
data: {
  error: {
    /** np. invalid_data, not_found, unreachable_data, timeout, database, 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` lub przekazanie parametrów w treści żądania zamiast w query stringu skutkuje błędem walidacji (`invalid_data`) lub `405`.

## Powiązane akcje

- `list` — lista konkurentów projektu (ta strona)
- `getRanking` (`/api/rank_tracker/reports/competitors/getRanking`) — ranking konkurentów względem projektu
- `getMatrix` (`/api/rank_tracker/reports/competitors/getMatrix`) — macierz pokrycia fraz przez konkurentów