get_player_matches

5 creditsStats + aggregationPOST /v1/get_player_matches

A player's matches with scores and ratings, filtered by season, surface or opponent

Use it when you need a player's matches to chart form or results by surface, round or opponent.

Parameters

player_idstringrequired: Player id from search_players.
seasonstring | numberoptional: Year.
surfaceenum: hard | clay | grass | carpetoptional
opponent_idstringoptional: Only matches against this player.
tournament_idstringoptional: Only this tournament edition, e.g. "188-2025".
drawenum: main | qualifyingoptional
limitintegeroptional: Max matches (default 50).
offsetintegeroptional

Notes

Over MCP, ask for it in plain English and the client calls get_player_matches itself. Point any MCP client at https://mcp.acesapi.com/mcp?key=YOUR_API_KEY.
Each call costs 5 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_player_matches \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "player_id": "3782",
  "surface": "clay",
  "limit": 3
}'

Response

json

{
  "tour": "ATP",
  "player_id": "3782",
  "name": "Carlos Alcaraz",
  "matches": [
    {
      "match_id": "173993",
      "tournament_id": "338-2026",
      "tournament": "Barcelona Open Banc Sabadell",
      "season": 2026,
      "surface": "clay",
      "indoor": false,
      "starts_at": "2026-04-16T04:00:00.000Z",
      "match_date": "2026-04-16",
      "draw": "main",
      "round": "Round 2",
      "round_order": 12,
      "court": "",
      "player1_id": "3782",
      "player1": "Carlos Alcaraz",
      "player1_country": "ESP",
      "seed1": 1,
      "player2_id": "3811",
      "player2": "Tomas Machac",
      "player2_country": "CZE",
      "seed2": null,
      "winner_id": "3811",
      "status": "final",
      "outcome": "walkover",
      "score": "w/o",
      "sets1": null,
      "sets2": null,
      "games1": null,
      "games2": null,
      "result": "loss",
      "opponent_id": "3811",
      "opponent": "Tomas Machac",
      "rating_before": null,
      "rating_after": null,
      "sets": []
    },
    {
      "match_id": "173995",
      "tournament_id": "338-2026",
      "tournament": "Barcelona Open Banc Sabadell",
      "season": 2026,
      "surface": "clay",
      "indoor": false,
      "starts_at": "2026-04-14T14:10:00.000Z",
      "match_date": "2026-04-14",
      "draw": "main",
      "round": "Round 1",
      "round_order": 11,
      "court": "Pista Rafa Nadal",
      "player1_id": "3782",
      "player1": "Carlos Alcaraz",
      "player1_country": "ESP",
      "seed1": 1,
      "player2_id": "4099",
      "player2": "Otto Virtanen",
      "player2_country": "FIN",
      "seed2": null,
      "winner_id": "3782",
      "status": "final",
      "outcome": "completed",
      "score": "6-4 6-2",
      "sets1": 2,
      "sets2": 0,
      "games1": 12,
      "games2": 6,
      "result": "win",
      "opponent_id": "4099",
      "opponent": "Otto Virtanen",
      "rating_before": 2307,
      "rating_after": 2308,
      "sets": [
        {
          "set_no": 1,
          "games1": 6,
          "games2": 4,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 1
        },
        {
          "set_no": 2,
          "games1": 6,
          "games2": 2,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 1
        }
      ]
    },
    {
      "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,
      "result": "loss",
      "opponent_id": "3623",
      "opponent": "Jannik Sinner",
      "rating_before": 2317,
      "rating_after": 2307,
      "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
        }
      ]
    }
  ],
  "count": 3,
  "next_offset": 3
}