Pagination и фильтры списков

Эндпоинт GET /v2/{sportSlug}/matches имеет два режима ответа: streaming (по умолчанию) и paginated (если передан хотя бы один из page / page_size).

Streaming режим (по умолчанию)

Если page и page_size не переданы — сервер отдаёт матчи потоком с ограничением в 6000 матчей, поэтому рекомендуется использовать постраничный запрос.

curl -H "Authorization: YOUR_KEY" \
  "https://api.api-sport.ru/v2/football/matches?date=2026-05-28&status=inprogress"

{
  "matches": [ /* ... */ ],
  "totalMatches": 134
}

totalMatches равно фактическому числу матчей в ответе (а не общему числу подходящих под фильтр в БД).

Paginated режим

Передайте page и/или page_size — сервер ответит постраничным режимом с totalPages.

Параметр	Диапазон	По умолчанию
page	1–100	1
page_size	1–500	500

curl -H "Authorization: YOUR_KEY" \
  "https://api.api-sport.ru/v2/football/matches?page=2&page_size=50"

{
  "matches": [ /* ровно page_size элементов или меньше на последней странице */ ],
  "page": 2,
  "pageSize": 50,
  "totalPages": 27
}

Запрос по списку ID

Альтернатива пагинации — ids с CSV-списком до 100 ID за один запрос:

curl -H "Authorization: YOUR_KEY" \
  "https://api.api-sport.ru/v2/football/matches?ids=12345,12346,12347"

При превышении 100 ID — 400 Bad Request с сообщением Too many IDs requested. Maximum 100 IDs allowed.

Доступные фильтры

Параметр	Применимо к	Описание
date=YYYY-MM-DD	/matches	Матчи на эту дату (UTC bounds).
status=...	/matches	Один из notstarted, inprogress, finished, canceled, postponed, interrupted, suspended, delayed, willcontinue. Одно значение, не CSV.
tournament_id=1,2,3	/matches, /calendar, /tournaments	Фильтр по турнирам.
season_id=...	/matches, /calendar	Один сезон.
category_ids=1,2,3	/matches, /calendar	Категории (страны/регионы).
team_id=...	/matches, /calendar	Матчи с участием команды.
exclude_amateur=true	/matches, /calendar	Скрыть amateur/editor матчи.
has_bk_odds=true	/matches	Только матчи с букмекерскими коэффициентами.
with_bk_odds=true	/matches, /matches/{id}	Включить рынки oddsBk в ответ.
bookmaker_ids=melbet	/matches, /matches/{id}	Фильтр по букмекерам в oddsBk.

Search-эндпоинт

/v2/{sportSlug}/search использует свою пагинацию: limit (1–50, default 20) + offset (0–500, default 0). См. Search.

Tips

• Рекомендуется использовать постраничный запрос матчей — запросы без page= ограничены количеством матчей (можете пропустить какие-то матчи).
• Используйте ids= когда у вас уже есть набор matchId — это дешевле, чем page-by-page обход.
• Кэшируйте finished/canceled матчи — они не меняются.