get_head_to_head

10 creditsMulti-tablePOST /v1/get_head_to_head

Matchup history between two teams with win/loss records.

Use it when you're previewing a matchup and want to know the rivalry history: who has the edge, recent results, and head-to-head record for a specific season or all-time.

Parameters

team1stringrequired: First team abbreviation
team2stringrequired: Second team abbreviation
seasonstringoptional: Filter to specific season
limitintegeroptional: Max games (1-100, default 20)
leagueenum: nhl | pwhl | ohl | whl | qmjhl | echl | ahl | ushloptional: League. Defaults to nhl. One of: nhl, pwhl, ohl, whl, qmjhl, echl, ahl, ushl.

Notes

Over MCP, ask for it in plain English and the client calls get_head_to_head itself. Point any MCP client at https://mcp.puckapi.com/mcp?key=YOUR_API_KEY.
Each call costs 10 credits, taken before it runs and refunded if the server errors.
Not the call you need? Find the right call by what you are trying to answer.

Request

curl -X POST https://mcp.puckapi.com/v1/get_head_to_head \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "team1": "BUF",
  "team2": "TOR",
  "season": "20252026"
}'

Response

json

{
  "team1": "BUF",
  "team2": "TOR",
  "record": {
    "BUF": 2,
    "TOR": 1
  },
  "total_games": 3,
  "games": [
    {
      "id": "2025020412",
      "season": "20252026",
      "gameDate": "2025-12-14",
      "homeTeam": "TOR",
      "awayTeam": "BUF",
      "homeScore": 3,
      "awayScore": 4,
      "gameState": "FINAL",
      "venue": "Scotiabank Arena"
    },
    {
      "id": "2025020623",
      "season": "20252026",
      "gameDate": "2026-01-28",
      "homeTeam": "BUF",
      "awayTeam": "TOR",
      "homeScore": 2,
      "awayScore": 5,
      "gameState": "FINAL",
      "venue": "KeyBank Center"
    }
  ]
}

Response fields

team1string: First team abbreviation
team2string: Second team abbreviation
recordobject: Win counts keyed by team abbreviation
record.[TEAM]integer: Wins for that team
total_gamesinteger: Every meeting in range, which the record counts; games lists the latest limit of them
games[].idstring: Game ID
games[].gameDatestring: Date
games[].homeTeamstring: Home team abbreviation
games[].awayTeamstring: Away team abbreviation
games[].homeScoreinteger: Home team score
games[].awayScoreinteger: Away team score