FOOTBALL API
Sign inRequest a key
The collectionDocumentationMembershipStatusSupport
Sign inRequest a key
Documentation / Clubs

FOOTBALL CLUB MATCHES API

Club matches
Complimentary key

Every match of a club, played and still to come, by season and home or away, paged. On the complimentary key it reads this season's Premier League.

GET/v1/clubs/{club_id}/matches
TRY ITComplimentary
Kept in this browser for every docs page. No key yet? Get a free key
GET https://api.footballapi.org/v1/clubs/cl_4x2bczxvv/matches?per_page=2
The answer appears below, with its status and time.
curl "https://api.footballapi.org/v1/clubs/cl_4x2bczxvv/matches?per_page=2" \
  -H "X-API-Key: your key"

PARAMETERS

club_idrequiredstringA club id from any match, table or club list, such as cl_a7vhnxhhh. In the path.
seasonintegerThe first year of the season: 2026 for 2026/27.From 2015, or the competition's first season
venuestringHome matches only, or away matches only.home or away
pageintegerWhich page, from 1.From 1 to 100,000
per_pageintegerRows on a page. Default 100.From 1 to 1,000
cursorstringmeta.next_cursor from the page before, passed back unchanged. Faster than page for long walks.

RETURNS

match_idstringOur id for the match, mt_ and 9 characters, the same in every answer and for good
kickoff_utcstringKickoff in UTC, ISO 8601
kickoff_datestringThe day of kickoff in UTC, YYYY-MM-DD
competitionstringThe competition's name in the collection, such as premier-league
season_start_yearintegerThe first year of the season: 2026 for 2026/27
match_statusstringWhere the match stands, such as finished or not started
full_time_resultnull or morehome, away or draw, at full time
half_time_resultnull or morehome, away or draw, at half time
country_namestringThe country, or World or Europe for a tournament
competition_namestringThe competition as people write it
venuestringhome or away when the table counts only those; null for both
opponent_idstringOur id for the other club
opponent_namestringThe other club
goals_fornull or moreGoals scored
goals_againstnull or moreGoals let in
regular_goals_fornull or moreGoals scored by the club in 90 minutes and added time
regular_goals_againstnull or moreGoals let in by the club in 90 minutes and added time
positionintegerPlace in the table
travel_kmintegerHow far the club came for this match, in kilometres; 0 at home
ground_namestringThe ground
city_namestringThe city of the ground
outcomenull or morewon, drawn or lost, for the club the answer is about

EXAMPLE ANSWER

200GET /v1/clubs/cl_4x2bczxvv/matches?per_page=2, taken 21 Oct 2026
{
  "data": [
    {
      "match_id": "mt_bz20hr56m",
      "kickoff_utc": "2027-05-30T15:00:00Z",
      "kickoff_date": "2027-05-30",
      "competition": "premier-league",
      "season_start_year": 2026,
      "match_status": "scheduled",
      "full_time_result": null,
      "half_time_result": null,
      "country_name": "England",
      "competition_name": "Premier League",
      "venue": "away",
      "opponent_id": "cl_7me91q2ds",
      "opponent_name": "Aston Villa",
      "goals_for": null,
      "goals_against": null,
      "regular_goals_for": null,
      "regular_goals_against": null,
      "position": 16,
      "travel_km": 160,
      "ground_name": "Villa Park",
      "city_name": "Birmingham",
      "outcome": null
    },
    {
      "match_id": "mt_7e6n522jz",
      "kickoff_utc": "2027-05-23T14:00:00Z",
      "kickoff_date": "2027-05-23",
      "competition": "premier-league",
      "season_start_year": 2026,
      "match_status": "scheduled",
      "full_time_result": null,
      "half_time_result": null,
      "country_name": "England",
      "competition_name": "Premier League",
      "venue": "home",
      "opponent_id": "cl_3pekhsfp3",
      "opponent_name": "Manchester United",
      "goals_for": null,
      "goals_against": null,
      "regular_goals_for": null,
      "regular_goals_against": null,
      "position": 16,
      "travel_km": null,
      "ground_name": "Tottenham Hotspur Stadium",
      "city_name": "London",
      "outcome": null
    }
  ],
  "meta": {
    "count": 2,
    "page": 1,
    "per_page": 2,
    "total": 1629,
    "total_pages": 815,
    "next_page": 2,
    "prev_page": null,
    "next_cursor": null,
    "request_id": "req_6bb9d249889b7e02"
  }
}

ERRORS

401unauthorizedNo key, or a key we do not know.
400bad_requestA parameter is missing or not in the right form; the message names it.
403upgrade_requiredAnything outside this season's Premier League, on the complimentary key.
404not_foundAn id or competition we do not have.
422unknown_parameterA parameter this endpoint does not take.
429quota_exceededThe day's 50 calls are used, on the complimentary key; they reset at 00:00 UTC.
PREVIOUSClubNEXTForm