Multi-table10 credits

get_head_to_head

Matchup history with win/loss records and margins

When to use it

You are previewing a matchup and want the recent history between two teams with margins.

Parameters

Name	Type	Required	Description
team1	string	yes	First team code
team2	string	yes	Second team code
season	string \| number	no	Season year. Omit for all-time.
limit	integer	no	Max games (default 20)

Request

bash

curl -X POST https://football-mcp-production.up.railway.app/v1/get_head_to_head \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "team1": "KC",
  "team2": "BUF",
  "limit": 5
}'

Over MCP, ask for it in plain English and the client calls get_head_to_head itself. Point any MCP client at https://football-mcp-production.up.railway.app/mcp?key=YOUR_API_KEY.

Response

json

{
  "team1": "KC",
  "team2": "BUF",
  "record": {
    "KC": 2,
    "BUF": 3,
    "ties": 0
  },
  "total_games": 5,
  "avg_margin_team1": -2.6,
  "games": [
    {
      "game_id": "2025_09_KC_BUF",
      "season": 2025,
      "game_type": "REG",
      "week": 9,
      "gameday": "2025-11-02",
      "weekday": "Sunday",
      "kickoff": "2025-11-02T21:25:00.000Z",
      "away_team": "KC",
      "home_team": "BUF",
      "away_score": 21,
      "home_score": 28,
      "result": 7,
      "total": 49,
      "overtime": 0,
      "status": "FINAL",
      "location": "Home",
      "stadium": "New Era Field",
      "roof": "outdoors",
      "surface": "a_turf",
      "temp": 54,
      "wind": 6,
      "div_game": false,
      "away_rest": 6,
      "home_rest": 7,
      "spread_line": -2.5,
      "total_line": 53.5,
      "away_moneyline": -135,
      "home_moneyline": 114,
      "away_qb_name": "Patrick Mahomes",
      "home_qb_name": "Josh Allen",
      "away_qb_id": "00-0033873",
      "home_qb_id": "00-0034857",
      "away_coach": "Andy Reid",
      "home_coach": "Sean McDermott",
      "referee": "Carl Cheffers",
      "espn_id": "401772768",
      "pfr_id": "202511020buf"
    },
    {
      "game_id": "2024_21_BUF_KC",
      "season": 2024,
      "game_type": "CON",
      "week": 21,
      "gameday": "2025-01-26",
      "weekday": "Sunday",
      "kickoff": "2025-01-26T23:30:00.000Z",
      "away_team": "BUF",
      "home_team": "KC",
      "away_score": 29,
      "home_score": 32,
      "result": 3,
      "total": 61,
      "overtime": 0,
      "status": "FINAL",
      "location": "Home",
      "stadium": "GEHA Field at Arrowhead Stadium",
      "roof": "outdoors",
      "surface": "grass",
      "temp": 31,
      "wind": 8,
      "div_game": false,
      "away_rest": 7,
      "home_rest": 8,
      "spread_line": 1.5,
      "total_line": 49.5,
      "away_moneyline": -102,
      "home_moneyline": -118,
      "away_qb_name": "Josh Allen",
      "home_qb_name": "Patrick Mahomes",
      "away_qb_id": "00-0034857",
      "home_qb_id": "00-0033873",
      "away_coach": "Sean McDermott",
      "home_coach": "Andy Reid",
      "referee": "Clete Blakeman",
      "espn_id": "401671887",
      "pfr_id": "202501260kan"
    },
    {
      "game_id": "2024_11_KC_BUF",
      "season": 2024,
      "game_type": "REG",
      "week": 11,
      "gameday": "2024-11-17",
      "weekday": "Sunday",
      "kickoff": "2024-11-17T21:25:00.000Z",
      "away_team": "KC",
      "home_team": "BUF",
      "away_score": 21,
      "home_score": 30,
      "result": 9,
      "total": 51,
      "overtime": 0,
      "status": "FINAL",
      "location": "Home",
      "stadium": "New Era Field",
      "roof": "outdoors",
      "surface": "a_turf",
      "temp": 50,
      "wind": 3,
      "div_game": false,
      "away_rest": 7,
      "home_rest": 7,
      "spread_line": 2.5,
      "total_line": 46.5,
      "away_moneyline": 120,
      "home_moneyline": -142,
      "away_qb_name": "Patrick Mahomes",
      "home_qb_name": "Josh Allen",
      "away_qb_id": "00-0033873",
      "home_qb_id": "00-0034857",
      "away_coach": "Andy Reid",
      "home_coach": "Sean McDermott",
      "referee": "Land Clark",
      "espn_id": "401671665",
      "pfr_id": "202411170buf"
    }
  ],
  "count": 5
}

Response fields

Field	Type	Description
team1	string
team2	string
record	object
record.KC	number
record.BUF	number
record.ties	number
total_games	number
avg_margin_team1	number
games[]	array	List of objects
games[].game_id	string
games[].season	number
games[].game_type	string
games[].week	number
games[].gameday	string
games[].weekday	string
games[].kickoff	string
games[].away_team	string
games[].home_team	string
games[].away_score	number
games[].home_score	number
games[].result	number
games[].total	number
games[].overtime	number
games[].status	string
games[].location	string
games[].stadium	string
games[].roof	string
games[].surface	string
games[].temp	number
games[].wind	number
games[].div_game	boolean
games[].away_rest	number
games[].home_rest	number
games[].spread_line	number
games[].total_line	number
games[].away_moneyline	number
games[].home_moneyline	number
games[].away_qb_name	string
games[].home_qb_name	string
games[].away_qb_id	string