Leagues & Countries

List matches in a league

Returns a paginated list of matches for a league with scores, xG, market odds, model probabilities, and venue. Supports filtering by season, team, status, date, and date range, plus sort order.

Plan: Available on the free plan.

get/leagues/{league_id}/matches

Request

  • Base URL: https://footballdata.io/api/v1
  • URL: https://footballdata.io/api/v1/leagues/{league_id}/matches
  • Auth: HTTP bearer

Path parameters

league_idinteger required

League ID whose matches to list. Must be > 0 or the endpoint returns missing_league_id (400). Caller must have league access.

Query parameters

season_idinteger

Filter to matches in this season. Ignored when <= 0.

team_idinteger

Filter to matches where this team played (home or away). Ignored when <= 0.

statusstring

Filter by exact match status string (e.g. complete, incomplete).

datestring

Filter to matches on this exact date (YYYY-MM-DD), matched against DATE(match_date).

fromstring

Lower bound date (YYYY-MM-DD); matches with match_date >= from 00:00:00.

tostring

Upper bound date (YYYY-MM-DD); matches with match_date <= to 23:59:59.

sortstring

Sort direction by match_date then id. Allowed: asc, desc (any non-'desc' value falls back to asc).

pageinteger

Page number, minimum 1.

limitinteger

Results per page, clamped between 1 and 100.

Response

Successful response

successboolean
metaMeta

Request metadata: usage counters, plan access, and pagination when applicable.

Example response

{
  "success": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.