get_matches

2 creditsBasic lookupPOST /v1/get_matches

Match results by day, tournament or season, with set and tiebreak scores

Use it when you want results by day or by round: a day's matches, or every final of a season.

Parameters

datestringoptional: UTC date, YYYY-MM-DD.
tournament_idstringoptional: Tournament edition id, e.g. "188-2025".
seasonstring | numberoptional: Year.
roundstringoptional: Round name as listed, e.g. "Final", "Semifinal", "Round 1".
statusenum: scheduled | live | finaloptional
limitintegeroptional: Max matches (default 100).
offsetintegeroptional

Notes

Over MCP, ask for it in plain English and the client calls get_matches itself. Point any MCP client at https://mcp.acesapi.com/mcp?key=YOUR_API_KEY.
Each call costs 2 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_matches \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "season": 2025,
  "round": "Final",
  "limit": 3
}'

Response

json

{
  "tour": "ATP",
  "matches": [
    {
      "match_id": "152433",
      "tournament_id": "971-2025",
      "tournament": "Bank of China Hong Kong Tennis Open",
      "season": 2025,
      "surface": "hard",
      "indoor": false,
      "starts_at": "2025-01-05T08:40:00.000Z",
      "match_date": "2025-01-05",
      "draw": "main",
      "round": "Final",
      "round_order": 22,
      "court": "Centre Court",
      "player1_id": "1035",
      "player1": "Kei Nishikori",
      "player1_country": "JPN",
      "seed1": null,
      "player2_id": "3308",
      "player2": "Alexandre Muller",
      "player2_country": "FRA",
      "seed2": null,
      "winner_id": "3308",
      "status": "final",
      "outcome": "completed",
      "score": "2-6 6-1 6-3",
      "sets1": 1,
      "sets2": 2,
      "games1": 10,
      "games2": 14,
      "sets": [
        {
          "set_no": 1,
          "games1": 6,
          "games2": 2,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 1
        },
        {
          "set_no": 2,
          "games1": 1,
          "games2": 6,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 2
        },
        {
          "set_no": 3,
          "games1": 3,
          "games2": 6,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 2
        }
      ]
    },
    {
      "match_id": "152358",
      "tournament_id": "970-2025",
      "tournament": "Brisbane International presented by ANZ",
      "season": 2025,
      "surface": "hard",
      "indoor": false,
      "starts_at": "2025-01-05T09:05:00.000Z",
      "match_date": "2025-01-05",
      "draw": "main",
      "round": "Final",
      "round_order": 22,
      "court": "Pat Rafter Arena",
      "player1_id": "2952",
      "player1": "Reilly Opelka",
      "player1_country": "USA",
      "seed1": null,
      "player2_id": "3754",
      "player2": "Jiri Lehecka",
      "player2_country": "CZE",
      "seed2": null,
      "winner_id": "3754",
      "status": "final",
      "outcome": "retired",
      "score": "4-1 ret.",
      "sets1": 0,
      "sets2": 0,
      "games1": 1,
      "games2": 4,
      "sets": [
        {
          "set_no": 1,
          "games1": 1,
          "games2": 4,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": null
        }
      ]
    },
    {
      "match_id": "152920",
      "tournament_id": "925-2025",
      "tournament": "ASB Classic",
      "season": 2025,
      "surface": "hard",
      "indoor": false,
      "starts_at": "2025-01-11T01:10:00.000Z",
      "match_date": "2025-01-11",
      "draw": "main",
      "round": "Final",
      "round_order": 22,
      "court": "Centre Court",
      "player1_id": "3356",
      "player1": "Zizou Bergs",
      "player1_country": "BEL",
      "seed1": null,
      "player2_id": "242",
      "player2": "Gael Monfils",
      "player2_country": "FRA",
      "seed2": null,
      "winner_id": "242",
      "status": "final",
      "outcome": "completed",
      "score": "6-3 6-4",
      "sets1": 0,
      "sets2": 2,
      "games1": 7,
      "games2": 12,
      "sets": [
        {
          "set_no": 1,
          "games1": 3,
          "games2": 6,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 2
        },
        {
          "set_no": 2,
          "games1": 4,
          "games2": 6,
          "tiebreak1": null,
          "tiebreak2": null,
          "winner": 2
        }
      ]
    }
  ],
  "count": 3,
  "next_offset": 3
}