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

żądanie-podstawowe.jsonc


{
  "project_id": null
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "project_id": null,
  "limit": 50,
  "page": 1
}

cURL


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

Parametry

Name	Type	Default
`project_id`	`number` 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`.
`limit`	`number` Liczba wierszy na stronę. Nieujemna liczba całkowita. Gdy pominięty, API może zwrócić wszystkie wiersze (`limit: null`).
`page`	`number` Numer strony. Nieujemna liczba całkowita.	`1`

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.

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

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [],
  "pagination": { "count": 0, "current_page": 1, "page_count": 1 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`Competitor[]` Lista konkurentów projektu (pusta, gdy żaden nie został skonfigurowany)
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number \| null; }` Metadane paginacji

Błędy

Name	Type	Default
`success`	`false`
`data`	`{ error: { type: string; message: string; params?: Record<string, Record<string, string>>; }; }`

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

Lista konkurentów (list)