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

FOOTBALL HEAD TO HEAD API

Head to head
Complimentary keyMCP tool head_to_head

Every meeting between two clubs since 2015/16, newest first, with the record of each side. On the complimentary key it reads this season's Premier League.

GET/v1/clubs/{club_id}/head-to-head/{opponent_id}
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/head-to-head/cl_frt0n2e46
The answer appears below, with its status and time.
curl "https://api.footballapi.org/v1/clubs/cl_4x2bczxvv/head-to-head/cl_frt0n2e46" \
  -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.
opponent_idrequiredstringThe other club's id. In the path.
limitintegerHow many meetings to list, newest first. Default 20.From 1 to 100

RETURNS

clubobjectThe club the answer is about
club.club_idstringOur id for the club, cl_ and 9 characters, the same in every answer and for good
club.club_namestringThe club
opponentobjectThe other club
opponent.club_idstringOur id for the club, cl_ and 9 characters, the same in every answer and for good
opponent.club_namestringThe club
recordobjectHow the meetings ended, from the first club's side
record.playedintegerMatches counted
record.wonintegerMatches won
record.drawnintegerMatches drawn
record.lostintegerMatches lost
record.goals_forintegerGoals scored
record.goals_againstintegerGoals let in
record.clean_sheetsintegerMatches without letting one in
record.failed_to_scoreintegerMatches without scoring
record.goal_differenceintegerGoals scored less goals let in
record.pointsintegerThree for a win, one for a draw
record.win_pctintegerShare of the matches won, as a percentage
record.goals_per_gamenumberGoals scored a match, on average
record.conceded_per_gamenumberGoals let in a match, on average
matcheslistMatches counted
matches[].match_idstringOur id for the match, mt_ and 9 characters, the same in every answer and for good
matches[].kickoff_datestringThe day of kickoff in UTC, YYYY-MM-DD
matches[].competition_namestringThe competition as people write it
matches[].venuestringhome or away when the table counts only those; null for both
matches[].goals_forintegerGoals scored
matches[].goals_againstintegerGoals let in
matches[].outcomestringwon, drawn or lost, for the club the answer is about

EXAMPLE ANSWER

200GET /v1/clubs/cl_4x2bczxvv/head-to-head/cl_frt0n2e46, taken 21 Oct 2026, first rows shown
{
  "data": {
    "club": {
      "club_id": "cl_4x2bczxvv",
      "club_name": "Tottenham"
    },
    "opponent": {
      "club_id": "cl_frt0n2e46",
      "club_name": "Coventry"
    },
    "record": {
      "played": 20,
      "won": 12,
      "drawn": 3,
      "lost": 5,
      "goals_for": 36,
      "goals_against": 24,
      "clean_sheets": 6,
      "failed_to_score": 3,
      "goal_difference": 12,
      "points": 39,
      "win_pct": 60,
      "goals_per_game": 1.8,
      "conceded_per_game": 1.2
    },
    "matches": [
      {
        "match_id": "mt_95kf4jw9a",
        "kickoff_date": "2026-10-19",
        "competition_name": "Premier League",
        "venue": "home",
        "goals_for": 3,
        "goals_against": 1,
        "outcome": "won"
      },
      {
        "match_id": "mt_fesgtwmrd",
        "kickoff_date": "2024-09-18",
        "competition_name": "League Cup",
        "venue": "away",
        "goals_for": 2,
        "goals_against": 1,
        "outcome": "won"
      },
      {
        "match_id": "mt_73qs7zd2d",
        "kickoff_date": "2013-01-05",
        "competition_name": "FA Cup",
        "venue": "home",
        "goals_for": 3,
        "goals_against": 0,
        "outcome": "won"
      }
    ]
  },
  "meta": {
    "count": 20,
    "request_id": "req_2448c5285e24cf6f"
  }
}

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.
PREVIOUSTravelNEXTGrounds