---
title: "Head to head"
method: POST
path: "/v1/get_head_to_head"
tags: ["Multi-table"]
---

# Head to head

`POST /v1/get_head_to_head`

## Request

- Base URL: `https://mcp.puckapi.com`
- URL: `https://mcp.puckapi.com/v1/get_head_to_head`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Use when comparing two teams' history. Returns recent matchups with win/loss record. Can filter by season or get all-time. Costs 10 credits.

## Request body

- object
  - `team1` string, required: First team abbreviation (e.g. BUF)
  - `team2` string, required: Second team abbreviation (e.g. TOR)
  - `season` string: Season ID, 8-digit (e.g. 20242025 for 2024-25). 2024-25 and 2024-2025 also accepted. Omit for all-time.
  - `limit` integer: Max games to return (default 20)
  - `league` 'nhl' | 'pwhl' | 'ohl' | 'whl' | 'qmjhl' | 'echl' | 'ahl' | 'ushl': League. Defaults to nhl. One of: nhl, pwhl, ohl, whl, qmjhl, echl, ahl, ushl.

## Response `200`

The result, wrapped in data.

- object
  - `data` object, required
    - `team1` string, required
    - `team2` string, required
    - `record` object, required
    - `total_games` number, required
    - `games` object[], required
      - `id` string, required
      - `season` string, nullable, required
      - `gameDate` string, nullable, required
      - `startTime` string, nullable, required
      - `homeTeam` string, required
      - `awayTeam` string, required
      - `homeScore` number, nullable, required
      - `awayScore` number, nullable, required
      - `gameState` string, nullable, required
      - `gameType` string, nullable, required
      - `venue` string, nullable, required

## Other responses

- `400`: Invalid arguments.
- `401`: Missing or invalid API key.
- `402`: Not enough credits.
- `429`: Rate limited.

---

[API](https://skmtc.dev/puckapi/apis/puckapi-api.md) · [All operations](https://skmtc.dev/puckapi/apis/puckapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/puckapi/apis/puckapi-api/revisions/99b3e5171ab4?raw)