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

curl -H "x-api-key: YOUR_API_KEY" \
  https://v1.football.sportsapipro.com/api/v1/h2h/131/132

Response (envelope shown, games array trimmed):

{
  "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 and grab competitors[].id:

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).
• 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 — single-team schedule.
• Game Detail — open any returned game ID.