---
title: "Matches"
method: POST
path: "/v1/get_matches"
tags: ["Basic lookup"]
---

# Matches

`POST /v1/get_matches`

## Request

- Base URL: `https://mcp.acesapi.com`
- URL: `https://mcp.acesapi.com/v1/get_matches`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Use for match results by day, tournament or season: each match with both players, seeds, round, status, score and sets (games and tiebreak points). Pass a date (YYYY-MM-DD, UTC), a tournament_id or a season; filter by round (e.g. "Final") and status. Tour: atp (default) or wta; on the shared endpoint pass league: "wta" for the WTA. Costs 2 credits.

## Request body

- object
  - `date` string: UTC date, YYYY-MM-DD.
  - `tournament_id` string: Tournament edition id, e.g. "188-2025".
  - `season` union: Year.
    - string
    - number
  - `round` string: Round name as listed, e.g. "Final", "Semifinal", "Round 1".
  - `status` 'scheduled' | 'live' | 'final'
  - `limit` integer: Max matches (default 100).
  - `offset` integer
  - `league` 'tennis' | 'wta': League. Defaults to tennis. One of: tennis, wta.

## Response `200`

The result, wrapped in data.

- object
  - `data` object, required
    - `tour` string, required
    - `matches` object[], required
    - `count` number, required
    - `next_offset` number, nullable

## Other responses

- `400`: Invalid arguments.
- `401`: Missing or invalid API key.
- `402`: Not enough credits.
- `429`: Rate limited.

---

[API](https://skmtc.dev/acesapi/apis/acesapi-api.md) · [All operations](https://skmtc.dev/acesapi/apis/acesapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/acesapi/apis/acesapi-api/revisions/01a182013f8b?raw)