get_head_to_head

3 creditsMulti-tablePOST /v1/get_head_to_head

Two players' meetings, wins by surface and in finals

Use it when you want two players' record against each other, by surface and in finals, with every meeting.

Parameters

player_idstringrequired: First player id.
opponent_idstringrequired: Second player id.

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.acesapi.com/mcp?key=YOUR_API_KEY.
Each call costs 3 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.acesapi.com/v1/get_head_to_head \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "player_id": "3623",
  "opponent_id": "3782"
}'

Response

json

{
  "tour": "ATP",
  "players": [
    {
      "player_id": "3623",
      "name": "Jannik Sinner"
    },
    {
      "player_id": "3782",
      "name": "Carlos Alcaraz"
    }
  ],
  "summary": {
    "matches": 17,
    "wins": {
      "3623": 7,
      "3782": 10
    },
    "sets_won": {
      "3623": 25,
      "3782": 26
    },
    "by_surface": {
      "clay": {
        "3623": 2,
        "3782": 3
      },
      "hard": {
        "3623": 3,
        "3782": 7
      },
      "grass": {
        "3623": 2,
        "3782": 0
      }
    },
    "in_finals": {
      "3623": 4,
      "3782": 5
    },
    "walkovers": 0
  },
  "matches": [
    {
      "match_id": "173907",
      "tournament_id": "42-2026",
      "tournament": "Rolex Monte-Carlo Masters",
      "season": 2026,
      "surface": "clay",
      "indoor": false,
      "starts_at": "2026-04-12T13:10:00.000Z",
      "match_date": "2026-04-12",
      "draw": "main",
      "round": "Final",
      "round_order": 22,
      "court": "Court Rainier III",
      "player1_id": "3782",
      "player1": "Carlos Alcaraz",
      "player1_country": "ESP",
      "seed1": 1,
      "player2_id": "3623",
      "player2": "Jannik Sinner",
      "player2_country": "ITA",
      "seed2": 2,
      "winner_id": "3623",
      "status": "final",
      "outcome": "completed",
      "score": "7-6(5) 6-3",
      "sets1": 0,
      "sets2": 2,
      "games1": 9,
      "games2": 13,
      "sets": [
        {
          "set_no": 1,
          "games1": 6,
          "games2": 7,
          "tiebreak1": 5,
          "tiebreak2": 7,
          "winner": 2
        },
        {
          "set_no": 2,
          "games1": 3,
          "games2": 6,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 2
        }
      ]
    },
    {
      "match_id": "167710",
      "tournament_id": "339-2025",
      "tournament": "Nitto ATP Finals",
      "season": 2025,
      "surface": "hard",
      "indoor": true,
      "starts_at": "2025-11-16T17:15:00.000Z",
      "match_date": "2025-11-16",
      "draw": "main",
      "round": "Final",
      "round_order": 22,
      "court": "Inalpi Arena",
      "player1_id": "3782",
      "player1": "Carlos Alcaraz",
      "player1_country": "ESP",
      "seed1": 1,
      "player2_id": "3623",
      "player2": "Jannik Sinner",
      "player2_country": "ITA",
      "seed2": 2,
      "winner_id": "3623",
      "status": "final",
      "outcome": "completed",
      "score": "7-6(4) 7-5",
      "sets1": 0,
      "sets2": 2,
      "games1": 11,
      "games2": 14,
      "sets": [
        {
          "set_no": 1,
          "games1": 6,
          "games2": 7,
          "tiebreak1": 4,
          "tiebreak2": 7,
          "winner": 2
        },
        {
          "set_no": 2,
          "games1": 5,
          "games2": 7,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 2
        }
      ]
    },
    {
      "match_id": "161412",
      "tournament_id": "189-2025",
      "tournament": "US Open",
      "season": 2025,
      "surface": "hard",
      "indoor": false,
      "starts_at": "2025-09-07T18:45:00.000Z",
      "match_date": "2025-09-07",
      "draw": "main",
      "round": "Final",
      "round_order": 22,
      "court": "Arthur Ashe Stadium",
      "player1_id": "3623",
      "player1": "Jannik Sinner",
      "player1_country": "ITA",
      "seed1": 1,
      "player2_id": "3782",
      "player2": "Carlos Alcaraz",
      "player2_country": "ESP",
      "seed2": 2,
      "winner_id": "3782",
      "status": "final",
      "outcome": "completed",
      "score": "6-2 3-6 6-1 6-4",
      "sets1": 1,
      "sets2": 3,
      "games1": 13,
      "games2": 21,
      "sets": [
        {
          "set_no": 1,
          "games1": 2,
          "games2": 6,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 2
        },
        {
          "set_no": 2,
          "games1": 6,
          "games2": 3,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 1
        },
        {
          "set_no": 3,
          "games1": 1,
          "games2": 6,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 2
        }
      ]
    }
  ]
}