AcesAPI Tool

Every other skill delegates data retrieval here. This skill owns the 13 tools, picks the cheapest call that answers the question, tracks credit cost, and says what the data cannot do.

Coverage (from acesapi.com/data, counted from the database): 123,394 ATP and WTA singles matches from 2007 to 2026, 1,637 weekly ranking lists, and sportsbook moneylines for 11,551 matches since 2020. Qualifying draws from 2022. Surfaces, ratings and head to head are computed by AcesAPI.

Connection

Every response is wrapped: {"data": {...}}. Unwrap data before reading fields. REST responses carry X-Credits-Used and X-Credits-Remaining headers.

Tours. ATP is the default. Pass "league": "wta" to any tool for the WTA (the enum also accepts tennis, which is the ATP default). Player ids and match ids are tour-specific strings: a WTA id used without league: "wta" will miss.

Ids are strings. player_id, match_id and tournament_id come back as strings ("3623", "157774", "188-2025"). Tournament edition ids are <tournament>-<season>. Seasons are four-digit calendar years.

When to Use Each Tool

Tool Selection Guide

Response Shapes (real, trimmed)

get_match (2 credits). Ratings are null until a match is played; odds is an array of one row per book:

{"data": {
  "tour": "ATP",
  "match": {"match_id": "157774", "tournament": "Wimbledon", "season": 2025, "surface": "grass",
    "round": "Final", "player1": "Jannik Sinner", "player2": "Carlos Alcaraz",
    "winner_id": "3623", "outcome": "completed", "score": "4-6 6-4 6-4 6-4",
    "sets": [{"set_no": 1, "games1": 4, "games2": 6, "tiebreak1": null, "tiebreak2": null, "winner": 2}]},
  "players": [{"player_id": "3623", "rating": {"before": 2325, "after": 2335, "surface_before": 1995, "surface_after": 2037}}],
  "stats": {"sets_played": 4, "total_games": 40, "tiebreaks": 0, "went_the_distance": false,
    "winner_lost_first_set": true, "serve_stats": null},
  "odds": [{"source": "archive", "book": "Pinnacle", "p1_open": 102, "p1_close": -116,
    "p2_open": -115, "p2_close": 105, "games_spread1": -0.5, "games_total": 41.5}]
}}

get_ratings returns ratings[] with rank, rating, player_id, name, surface_matches, last_match, plus a method string describing the Elo.

get_head_to_head returns summary (matches, wins keyed by player id, sets_won, by_surface, in_finals, walkovers) and matches[].

Paginated tools (list_tournaments, get_matches, get_player_matches) return count and next_offset; pass it back as offset.

What the Data Does Not Contain

• No serve or return statistics. No aces, double faults, break points or first-serve percentages. get_match returns serve_stats: null with a note that they are not published. Anything that needs serve percentage must be built from score proxies (see set-score-modeling) or from the user's own data.
• No odds tool. Moneylines exist only inside get_match. Grand Slam matches from mid-2020 and ATP Masters and WTA 1000 matches from August 2024; the array is empty elsewhere. Lines are pre-match, open and close per book, refreshed hourly. No in-play prices and no props.
• Rankings are the top 100 to 150 per week. current_rank in search_players is null outside that list.
• No injuries, lineups, weather, court speed or betting percentages.
• Walkovers are listed but not counted as wins in head to head. Walkovers, defaults and retirements are not rated by the Elo.

Commands That Do NOT Exist

Season and Surface Resolution

• The tour year is the calendar year. "This season" is the current calendar year; the tour runs from early January to November.
• Surfaces: hard, clay, grass, carpet. Carpet is nearly empty in modern years. indoor is a separate flag on matches and tournaments, so indoor hard is surface: "hard" with indoor: true.
• Typical swing: indoor hard and Australia (January to March), clay (April to early June), grass (June to July), North American hard (August to September), Asian and indoor hard (September to November).

Credit Planning

Warn before any loop of get_match or get_player_matches calls. State the count and the credits first.

Anti-patterns

What to Do Next