# Live Tennis API — API Reference > Complete endpoint reference for the Live Tennis API. Real-time tennis scores, > players, rankings, match-winner market prices and model win-probability for ATP, > WTA, Challenger and ITF, over REST and WebSocket — plus the point-by-point tape > (2023→now) and the results archive (1968–2022) of deep historical results. Base URL: https://api.livetennisapi.com/api/public/v1 Full text reference: https://docs.livetennisapi.com/reference.html OpenAPI spec: https://docs.livetennisapi.com/openapi.yaml Website: https://livetennisapi.com ## Quickstart (no code required) Open this in a browser — no install, no headers: https://api.livetennisapi.com/api/public/v1/matches?status=live&token=YOUR_KEY Reading a score: every array is PLAYER-MAJOR — first list is player 1, second is player 2. "sets": [1,0] = p1 leads one set to nil. "games": [[6,3],[4,4]] = 6-4 in the first set, 3-4 in the second. "points": ["0","0"] = the game in progress. "server": 1 = player 1 serving. ## Authentication Send the API key as `Authorization: Bearer `, `X-API-Key: `, or `?token=` in the query string. The query form is browser-friendly (clickable links, phones); prefer a header for anything automated, since URLs leak into logs, history and referrers. The /health endpoint requires no key. ## Plans Every plan includes the plans below it. The concrete deltas: - FREE ($0, no card) — live & upcoming matches, current scores, players, fixtures, usage stats. 30 req/min, 100 req/day. No history, no market prices, no model fields, no WebSocket. - BASIC ($9.99/mo) — adds history, in two continuous halves: the point-by-point tape (2023→now) — the completed-match listing and the per-match tape with the model win-probability at every point — and the results archive (1968–2022): deep results, archive player bios, career aggregates and head-to-head (/h2h). 60 req/min, 1,000 req/day. - PRO ($29.99/mo) — adds match events, market prices, bulk history packages (JSONL/CSV), and the rank-ordered rankings listing. 300 req/min, 10,000 req/day. - ULTRA ($99.99/mo) — adds model analysis, live win_probability_p1 + danger, in-play match statistics, per-player as-of rankings, rally construction (shot-by-shot charted data), the WebSocket push feed and webhooks. 600 req/min, 500,000 req/day. Coverage is identical on every plan (all tours, ATP through ITF); plans differ in which data products and volumes they unlock. Calling above your plan returns 403 {"error":"upgrade_required"}. ## Historical Data API (standalone plans for the /history endpoints) - Starter — single-match point-by-point tape reads (tape + model win-probability per point), all tours, one match per request. No bulk downloads. - Pro — everything in Starter + bulk monthly package downloads + higher rate limits. - Business — everything in Pro + year-scale archive exports + top rate limits + priority support. - One-off passes — 1-month and 1-year access, no subscription. Prices: https://livetennisapi.com/historical-tennis-data-api ## Break-point Alerts (hosted alerts, no code) - Free — high-swing break points only (probability swing >= 0.15), one delivery channel. - Pro ($9.99/mo) — every break point (no swing floor), unlimited channels: Telegram, Discord, email, SMS, WhatsApp. ## Endpoints - GET /health — Liveness probe (no auth) - GET /matches — List matches by lifecycle status (FREE) - GET /matches/{matchId} — Full match detail (FREE; +market PRO, +analysis ULTRA) - GET /matches/{matchId}/score — Current score only — lowest-latency REST read (FREE) - GET /matches/{matchId}/events — Match events, newest first (PRO) - GET /matches/{matchId}/analysis — Model analysis for a match (ULTRA) - GET /matches/{matchId}/statistics — In-play statistics — aces, double faults, serve split, hold/break %, break points, service & return points (ULTRA) - GET /players — Search players by name (FREE) - GET /players/{playerId} — One player's bio + ranking + cached stats (FREE) - GET /tournaments — Tournament catalogue — the id space `Match.tournament_id` joins (FREE) - GET /tournaments/{tournamentId} — One tournament by its stable id (FREE) - GET /markets — Match-winner market(s) for a match (PRO) - GET /markets/{matchId}/prices — Market + recent price ticks per side, newest first (PRO) - GET /matches/{matchId}/prices — Bare price ticks of the mapped match-winner market, newest first (PRO) - GET /history/matches — Completed matches, newest first, with derived winner and tape coverage (BASIC) - GET /history/matches/{matchId} — Per-match tape — point-by-point score + per-point model probabilities (BASIC) - GET /history/archive/matches — Results archive (1968–2022) — deep historical results (BASIC) - GET /history/archive/matches/{archiveId} — One archive result, with serve statistics where recorded (BASIC) - GET /history/archive/players — Archive player bios — hand, DOB, country, height, career-high (BASIC) - GET /history/archive/career — Career aggregates over the results archive, 1968–2022 (BASIC) - GET /h2h — Head-to-head across the results archive (1968–2022) and our own completed matches (2023→now) (BASIC) - GET /history/packages — List the pre-built monthly bulk history packages (PRO) - GET /history/packages/{period} — One monthly package — manifest, or the bulk file itself (PRO) - GET /fixtures — Upcoming scheduled fixtures, earliest first (FREE) - GET /usage — Your own usage vs quota (FREE — any tier) - GET /rankings — Rankings — rank-ordered listing (PRO), or per-player as-of records (ULTRA) - GET /rally/matches — Charted matches with shot-by-shot data (ULTRA) - GET /rally/matches/{rallyMatchId} — Rally construction for one charted match (ULTRA) - GET /history/matches/{matchId}/rally — Rally construction by OUR match id (ULTRA) - GET /charting/players — Career shot-level charting aggregate for one player (ULTRA) - GET /charting/matches/{chartingMatchId} — One charted match, every stat family for both players (ULTRA) - POST /webhooks — Register an outbound webhook (ULTRA, direct keys only) - GET /webhooks — List your webhooks (ULTRA, direct keys only; never includes the secret) - DELETE /webhooks/{webhookId} — Remove one of your webhooks (ULTRA, direct keys only) - GET /ws-token — Mint a connection token for the high-fan-out push feed (ULTRA) ## FAQ How much data can I access on each plan? FREE = the current state only, 100 req/day. BASIC = + every completed match and its full point-by-point tape, one match per request, 1,000/day. PRO = + whole months of history in one bulk file, plus events and market prices, 10,000/day. ULTRA = + model analysis and live push, 500,000/day. How far back does history go? 1968, in two continuous halves. The point-by-point tape (2023→now): /history/matches pages every completed match from January 2023 on (filter with from/to). The results archive (1968–2022): /history/archive/matches serves winner/loser-shaped results — ATP and WTA, main draws, qualifying and the ITF/futures tiers, 1968 through 2022 — with seeds, ranks at the time, and serve stats where the era recorded them (from 1991). The archive ends where the tape begins. GET /history/packages lists exactly which bulk periods exist (monthly for tape, yearly for ?kind=archive) and is always the authoritative answer. What's in the point-by-point tape? One timestamped row per recorded point state: sets, per-set games, in-game points, server, tiebreak flag, and the model's win_probability_p1 + danger at that point. ## Official client libraries - Python: `pip install livetennisapi` — https://github.com/livetennisapi/livetennisapi-python - JavaScript/TypeScript: `npm install livetennisapi` — https://github.com/livetennisapi/livetennisapi-js - MCP server for LLM agents: `npx livetennisapi-mcp` — https://github.com/livetennisapi/livetennisapi-mcp ## Affiliate programme - https://affiliates.livetennisapi.com/program — 51% recurring commission for the lifetime of every subscription referred, 10% discount for the referred customer, 30-day attribution. - Free to join, open to developers, creators and tennis writers: https://affiliates.livetennisapi.com/signup ## Notes - Timestamps are UTC ISO 8601 with a Z suffix. - List endpoints return {data, meta}; single resources return the object directly. - limit defaults to 50, maximum 200; paginate with offset. - Additive changes ship within v1: clients must ignore unknown fields. - Score `games` is player-major: [[6,3,2],[4,6,1]] reads 6-4, 3-6, 2-1.