> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportsapipro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Head-to-Head

> All past games between two teams, in any sport.

The H2H endpoint returns every recorded meeting between two competitors, ordered most-recent first.

## Endpoint

```
GET /api/v1/h2h/{competitorId1}/{competitorId2}
```

Sport-scoped variant: `GET /api/v1/{sport}/h2h/{id1}/{id2}` (recommended — routes through the correct sport host).

## Example: Real Madrid vs FC Barcelona

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  https://v1.football.sportsapipro.com/api/v1/h2h/131/132
```

Response (envelope shown, games array trimmed):

```json theme={null}
{
  "success": true,
  "type": "head2head",
  "data": {
    "lastUpdateId": 5677082919,
    "ttl": 60,
    "summary": {
      "competitor1Wins": 6,
      "competitor2Wins": 5,
      "draws": 1,
      "totalGames": 12
    },
    "countries": [],
    "competitions": [],
    "games": [
      {
        "id": 4467358,
        "startTime": "2026-04-04T14:15:00+00:00",
        "statusGroup": 4,
        "competitionDisplayName": "LaLiga",
        "homeCompetitor": { "id": 132, "name": "FC Barcelona", "score": 1 },
        "awayCompetitor": { "id": 131, "name": "Real Madrid",  "score": 2 }
      }
    ]
  }
}
```

## Resolving team IDs first

If you don't already know the IDs, run [Search](/api-reference/v1-legacy/search) and grab `competitors[].id`:

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://v1.football.sportsapipro.com/api/v1/search?q=real%20madrid"
```

## Common patterns

* **Pre-match widget** — fetch H2H + last 5 results for each side ([`/competitor/{id}/results`](/api-reference/v1-legacy/teams)).
* **Streak detection** — walk `games[]` and count consecutive `isWinner` on one side.
* **Cross-competition** — H2H spans every competition both teams have ever met in. Group by `competitionDisplayName` if you only want league meetings.

## Related

* [Teams](/api-reference/v1-legacy/teams) — single-team schedule.
* [Game Detail](/api-reference/v1-legacy/games) — open any returned game ID.