Live Tennis API — Full Reference

GET /health

Liveness probe (no auth)

Plan required: — · operationId: healthCheck

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/health

GET /matches

List matches by lifecycle status (FREE)

Plan required: FREE · operationId: listMatches

status=live and status=upcoming are the FREE current-state picture. status=completed pages historical results and is part of the paid History product — it requires BASIC (the same rule as /history/matches). A FREE key may spend its 20 free history calls per calendar month here; past that the answer is 403 upgrade_required carrying free_history_taste: "used". The player, country, from/to, tour, draw, has_analysis and has_market filters are optional, AND-composed, applied inside the query (before pagination), and work on every status — omitting them returns exactly what the endpoint returned before they existed. has_analysis and has_market are the two availability flags every row already carries: filter the slate with them and call /matches/{matchId}/analysis and /matches/{matchId}/prices only for the ids that have something, rather than probing per match for a 404.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}

Full match detail (FREE; +market PRO, +analysis ULTRA)

Plan required: FREE · operationId: getMatch

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953 \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/score

Current score only — lowest-latency REST read (FREE)

Plan required: FREE · operationId: getMatchScore

This is a POINT-IN-TIME SNAPSHOT: the single current state, overwritten on every score commit. It carries no history and no accumulated statistics. For the SEQUENCE of states — who served each game, hold/break, every score state in forward order — use /history/matches/{matchId}?sequence=clean, which works on a LIVE match, not only a completed one. For in-play statistics use /matches/{matchId}/statistics (ULTRA); they are deliberately not on this object, because they can be further behind the match than the score and must carry their own as_of. ARCHIVED FINALS (since 2026-09-20). The live-score rows behind this read are retired by a 90-day retention sweep, and a match recovered from an official day list may never have had one. When there is no live row at all, a SETTLED match — outcome non-null on the match object: completed, retired, walkover, default, abandoned, unresolved — is answered from its archived final: the same read GET /matches?status=completed already embeds, through the same serializer, so the listing and this endpoint can never disagree about whether a score exists. A live tape always outranks the archive — the fallback is reached only when no publishable live row exists, so a live match reads exactly what it did before. An archived final carries age_seconds: null, observed_age_seconds: null, sources_count: null and accepted_at: null — no clock is claimed for a state nobody watched — and timestamp is null where the archived row has none (a reconstructed final). The Score object carries no data-source label; whether that final was observed or reconstructed is what GET /history/matches/{matchId} reports once, in meta.point_source. 404 is kept for: an upcoming match with no row (nothing to serve yet), a cancelled match that was never played (nothing settled), and a settled match with nothing recorded anywhere — the fallback serves a final that exists, it never invents one. Before 2026-09-20 every settled match older than the retention window answered 404 here (13,437 completed matches from the previous 180 days, 157,170 all time, measured at the change) while the completed listing served its score.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/score \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/events

Match events, newest first (PRO)

Plan required: PRO · operationId: listMatchEvents

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/events \
  -H "Authorization: Bearer twjp_..."

GET /events

Slate-wide events feed — every match's events in one call, oldest first, cursor by id (PRO)

Plan required: PRO · operationId: listSlateEvents

Added 2026-09-13. The rows of GET /matches/{matchId}/events for EVERY match in one request, so a poller watching the whole live slate spends one request per tick rather than one per match. after_id returns rows with id greater than the one passed, ascending, and meta.next_cursor names the last id served (null on a short page = caught up); since (UTC instant) is the first-call lower bound; with neither the newest page is served, still ascending. type narrows to a comma-separated list of event types or the family name stoppages (stoppage_*, pause_*, medical_timeout_*, trainer_called*, toilet_break_*). Rows carry id and match_id next to the per-match fields. Measured 2026-09-13: a scorer-stated stoppage reaches the feed a median 8 s (p90 13 s) after the scorer's own instant; the WebSocket stoppages signal pushes the same row as it is written.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/events \
  -H "Authorization: Bearer twjp_..."

GET /players/{playerId}/stoppages

One player's in-match stoppages and did-not-finish outcomes, newest first over a window (PRO)

Plan required: PRO · operationId: listPlayerStoppages

Added 2026-09-16. Medical timeouts and trainer calls on the player's matches (from the stoppage family of GET /matches/{matchId}/events), plus retirements and walkovers where THIS player is the non-winner, merged and sorted by at descending. Window: since/until (ISO date or UTC instant; default the last 180 days; at most 366 days, else 400 window_too_long). kind filters the seven row kinds (default medical_timeout,trainer_called,retirement,walkover); before pages by meta.next_cursor. meta.latest_medical_timeout and previous_medical_timeout are the two newest medical timeouts in the window whatever the page or the kind filter. meta.record_starts states how far back each family goes: stoppage rows exist from 2026-09-12 only; outcome rows from the oldest match with a stated winner. In-match stoppages and match outcomes only — no off-court injury record exists here. Same PRO capability as /events. GET /players/{playerId}/injuries serves the identical response.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/players/1104/stoppages \
  -H "Authorization: Bearer twjp_..."

GET /players/{playerId}/injuries

Alias of /players/{playerId}/stoppages — the identical response (PRO)

Plan required: PRO · operationId: listPlayerInjuries

Added 2026-09-16. The same handler, parameters, rows and meta as /players/{playerId}/stoppages, under the word the request used. The honest name is stoppages: nothing here is a diagnosis, only what the scorer, umpire or result stated.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/players/1104/injuries \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/status-history

The per-match status ledger — every status / event_status transition with its UTC instant (BASIC, history)

Plan required: BASIC · operationId: getMatchStatusHistory

Added 2026-09-12. Append-only, oldest first: one row per change of status and/or event_status, with the instant we published it, the value before and the effective value after, the derived outcome, and the newest score row at that instant. A correction is a new row, never an edit — a close published as unresolved and later confirmed shows the flip to completed; a completion that reopened shows completed -> live. basis: observed rows exist from 2026-09-11T22:45:48Z; basis: backfill rows (2026-09-12) were reconstructed from the one stamp per kind the match row kept before the ledger existed (last promotion to live from 2026-09-05, completion instant from 2026-08-21, last reopen, last event_status change) — one row per stamp, overwritten intermediate transitions are not recovered. A correction to a PUBLISHED result — status, event_status, winner or the final score changing after the match was first published as completed — is a new row with basis: restatement (from 2026-09-22), never a silent edit; result_restated_at / result_version on the match summarise them and GET /history/matches?restated_since= finds them. History capability (BASIC and the Historical Data plans), like the tape.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/status-history \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/analysis

Model analysis for a match (ULTRA)

Plan required: ULTRA · operationId: getMatchAnalysis

The model's thesis and profile for one match. COVERAGE IS NOT UNIVERSAL, and a polling client should plan for that. Analysis is produced per match by the model pipeline rather than emitted for every fixture: over the seven days to 2026-08-27, 1,225 of 2,863 matches that went live or completed carried one (42.8%). A match that has none yet returns 404 {"error":"no_analysis"} (since 2026-09-02; before that the body was a bare not_found) — that is the documented absence, not a fault, and it can turn into a 200 later in the same match once the pipeline has run. Never treat this 404 as a reason to retry harder. The body names which absence it is: not_found is an id that does not exist; no_analysis carries match_id and coverage: "none" for a real match with nothing computed. FILTER THE SLATE FIRST. Every row of GET /matches and the detail carries has_analysis (every tier), the same fact this endpoint answers 404 about — read it there and call only the matches that carry one, instead of spending one 404 per match. ONE CALL INSTEAD OF THREE. GET /matches/{matchId} carries the same thesis and profile in its analysis key on ULTRA, alongside market and market_price on PRO and above, next to the live score. It answers 200 whether or not analysis and a market exist — the keys are null instead — so a per-match poll built on the detail route replaces the score, analysis and prices calls with one request and never spends a call on a 404.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/analysis \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/statistics

In-play statistics — aces, double faults, serve split, hold/break %, break points, service & return points (ULTRA)

Plan required: ULTRA · operationId: getMatchStatistics

In-play statistics for one match, in TWO families that are deliberately not merged. DERIVED (the top level of players.pN) are rebuilt from the point-by-point record: service and return games played and won, hold and break percentage, break points faced, saved and converted, service and return points. MEASURED (players.pN.measured) are counted upstream, so they include what no point record can yield — ACES AND DOUBLE FAULTS, the first- and second-serve split, winners and unforced errors. Both families name some of the same quantities, computed two entirely different ways; that is a cross-check, not a duplication to collapse. Measured coverage is not uniform and every measured field is optional — an absent field is OMITTED, never zero-filled, so read the keys you are given. Aces and double faults are present across every tour. The serve split and break points saved are present on the main tours and absent on ITF singles. Winners and unforced errors historically appeared on a minority of main-tour matches and have not been delivered upstream since 2026-07-12 (measured 2026-08-17). freshness.derived and freshness.measured each carry their own coverage (live | final | stale | none | diverged; final = the closing figures of a completed match — a finished match cannot be "stale", so its age_seconds is null), as_of, age_seconds and describes — the match state the numbers describe. On diverged the measured VALUES are withheld and freshness.measured_divergence says why; the top-level coverage only summarises the response. none on both returns 200 with null players, not 404 — the match exists and holding nothing for it is the honest answer. THE TWO AGES USE DIFFERENT CLOCKS AND MUST NOT BE COMPARED. The derived age is measured against the newest SCORE row, because between points there is no new score either and wall-clock age would report staleness that does not exist. The measured age is wall clock, because those are fetched on a fixed cadence. Tiebreak games are excluded from the DERIVED family and counted separately; the live record collapses a whole tiebreak onto one entry, so most of its points are lost.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/statistics \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/points

Live per-point events in seq order — the REST catch-up for the WebSocket point stream (ULTRA)

Plan required: ULTRA · operationId: getMatchPoints

The live per-point event stream of one match, in seq order. The WebSocket point frames are best-effort with NO replay, so this endpoint is how you join mid-match and how you recover a dropped connection: subscribe the WS first, then GET with after_seq set to the last seq you hold, then dedup everything by seq — it is per-match, monotonic and never skips a value, so it is the whole reconciliation key. seq IS ARRIVAL ORDER, NOT MATCH ORDER, ON THE LIVE BASIS. It is assigned in the order points are committed, and a live match is fed by more than one upstream at different speeds, so a point from a set that has just ended can be committed AFTER points from the set that follows it and carry the higher seq. Each row is self-consistent — its set, game, number, score, sets and games all describe the point that was played — but reading the tape in seq order can show the set or game counter step backwards. Measured over a recent seven-day window this affected a minority of live matches, and never the reconstruction basis. So seq is the right key for paging, dedup and resume (unique, stable, strictly increasing — all after_seq needs) and the wrong key for chronology: sort by (set, game, number) to replay in playing order. That tuple ORDERS points; it does not IDENTIFY them. number is null wherever we joined a game already in progress, and the same tuple can appear on more than one row — a game re-expanded by a second source re-asserts ordinals it already holds, which on the live basis is a normal re-statement rather than a correction. There is no revision id, superseded-seq or correction flag: rows are append-only and never rewritten, so after_seq never needs a refetch, and the page-level quality field reads revised when the page contains such a re-statement. On the reconstruction basis of a completed match, seq is contiguous 1..N in true match order and the two agree. READ THE COVERAGE HONESTLY BEFORE YOU BUILD ON IT. A match's stream is per-point ONLY where a point-level feed covers it: pbp_coverage: "point" means a per-point stream has DELIVERED for this match — at least one played point past the seq 1 opener; "game" means no played point has arrived — only the snapshot score path covers it, or the stream holds only its opener so far (a listed match that has not started). An answer, not an error; it flips to point on the first played point. To admit a match as advancing, gate on sequence > 1 (a seeded match is 1) together with stale: false. Per-point coverage is never promised slate-wide; ITF and qualifying coverage in particular is partial. quality: "revised" means the upstream feed rewrote an already-served prefix at least once during this match; served rows are never edited (append-only). Each row is the state AFTER a played point: score/sets/games (tiebreaks carry the running count in score with games frozen at the pre-breaker score), its position (set/game/number), server (of the next point), the derived winner (null when not attributable to a single point — never guessed), and ts — CAPTURE time, when our pipeline committed the state, because no feed asserts a per-point clock and we fabricate none. Up to 500 rows per page; after_seq=last_seq fetches the next page while has_more is true. 404 unknown match; 400 points_disabled while the surface is switched off server-side. COMPLETED MATCHES: the stored live stream is served on a completed match too, whenever it is itself measured complete (the match-closing point included) or carries serve/outcome tags and is legal end to end (every transition one attributable point, judged in playing order). A projection never carries a clock or a tag, so a complete tagged stream is strictly more information than any reconstruction of the same match. Only when the stream falls short — no rows at all, incomplete and untagged, or a transition nobody can attribute — and a measured-complete recorded point sequence of the finished match exists does this endpoint serve THAT instead: the complete sequence projected into the same point-frame shape, love-love opener through the match-closing point, seq contiguous 1..N. The response field basis says which base served the page: live (the persisted live stream rows) or reconstruction (the projected complete sequence; quality is clean, every transition measured legal), and on reconstruction basis_reason says why the stream was not served: stream_absent (no stored stream rows), stream_incomplete (the stream is legal but does not measure complete — it joined mid-match or stopped short — and carries no tags) or stream_illegal (at least one transition is not attributable to one point: a gap or a torn row). When the reconstruction serves it serves wholesale — the two sequences are never interleaved (they share no key, so any merge would fabricate an order). On projected frames ts is null on every row: the recorded sequence carries no per-point clock and we fabricate none. after_seq pagination and seq dedup work identically on either basis, but the two bases are different sequences: if a completed match reads reconstruction, re-read from after_seq=0 rather than resuming a live cursor into it. Precedence fixed 2026-09-21: until then a measured-complete recorded sequence displaced the stream unconditionally, so a completed match could lose its tags the moment a reconstruction landed. THE MATCH-CLOSING POINT (added 2026-09-20). Every row is the state AFTER a point, so the point that wins a game is carried by the next game's number: 0 opener — and the point that wins the match had no next row to be carried by: the live stream never held it, and a serve statistic built off the stream was missing every match's last point. On a COMPLETED match served on the live basis the page now closes with ONE terminal row: seq = last + 1, number 0, sets/games the final score, score {"p1":"0","p2":"0"}, tiebreak false, server null (nobody serves next), winner the match winner, ts the instant the final score was observed. It is built at read time from the stream's last row and the observed final score, and only when the two are one point apart — the winner held game point and the final is the decided score; nothing is fabricated otherwise. serve, outcome and tagged_at on that row are null: no source's tag for a match's last point is stored yet. When the match ends in a tiebreak (added 2026-09-21) the stream's last row is the decisive tiebreak score itself (7-3, 8-6) and the closing row is the set roll-up after it: the next game number, number 0, tiebreak false, sets incremented for the tiebreak winner, the set banked 7-6 in games, score 0-0, server null, the same winner — the same row the stream stores after every other set-ending tiebreak. The response field ends_at_final says whether the sequence served ends on the match-closing point: false on a completed match whose stream stops short of it — a retirement or walkover (no closing point was played), a capture that stopped two or more points short, or a closer that cannot be stated as one point (from deuce, or from a 10-point match tiebreak). Always false on a live match. On the reconstruction basis it is judged from the projected sequence's last frame (a complete recorded sequence of a retired match ends at the retirement, so it reads false there). WebSocket and push frames are unchanged. REVISIONS: changed_since (added 2026-09-20). after_seq is a cursor by seq, so it can never return a row you already hold — and a serve/outcome tag that lands late lands on exactly such a row. Every row now carries tagged_at, the UTC instant its tags landed (null while none has). Pass changed_since=<ISO-8601 instant> (e.g. 2026-09-20T00:35:18Z; Z or an offset, a naive value is read as UTC, a date alone is refused) to get only the rows whose ts OR tagged_at is later than that instant, in seq order, paged like any other read and composable with after_seq. The post-match recipe: read the match, keep the instant, re-read with changed_since=<that instant> and replace the rows you hold by seq — no socket, no full re-fetch. Anything that is not an ISO-8601 timestamp is a 400 bad_changed_since. On the reconstruction basis no row carries a clock or a tag, so a changed_since read of it is an empty page: that sequence is final at first read.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/points \
  -H "Authorization: Bearer twjp_..."

GET /players

Search players by name (FREE)

Plan required: FREE · operationId: searchPlayers

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/players \
  -H "Authorization: Bearer twjp_..."

GET /players/{playerId}

One player's bio + ranking + cached stats (FREE)

Plan required: FREE · operationId: getPlayer

playerId is a ROSTER id — the live player registry, the id space /players, /matches and /rankings all speak. It is NOT the archive corpus person id. The results archive (1968–2022) keeps its own person registry, and archive match rows publish those ids as winner.player_id / loser.player_id. The two spaces are disjoint: no corpus id resolves here, and since 2026-09-20 a 404 for one says so and points at /history/archive/players?id={playerId}, which is where that id is read. A 404 with no see field is simply an id we do not hold.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/players/1104 \
  -H "Authorization: Bearer twjp_..."

GET /tournaments

Tournament catalogue — the id space Match.tournament_id joins (FREE)

Plan required: FREE · operationId: listTournaments

Stable tournament identity, one row per tournament × event type, stable across seasons. city/country come from a curated table and category only where our catalogues agree unambiguously on an exact-name join — each is null otherwise, never derived from the tournament name. Each row also carries the CURRENT season's tier / tier_source (added 2026-09-22) — the level in a closed vocabulary (atp_500, challenger_125, wta_125, itf_w35 … | null); the tier is per season, so a match carries its own.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/tournaments \
  -H "Authorization: Bearer twjp_..."

GET /tournaments/{tournamentId}

One tournament by its stable id (FREE)

Plan required: FREE · operationId: getTournament

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/tournaments/{tournamentId} \
  -H "Authorization: Bearer twjp_..."

GET /markets

The match's match-winner market (PRO)

Plan required: PRO · operationId: listMarkets

The match-winner market mapped to this match — data holds at most one object, and meta.count is 0 when nothing is mapped. MATCH-WINNER ONLY. No handicaps or game spreads, no totals, no set-winner books, and no per-game or per-set derivative of any kind. A quote here is the probability that a player WINS THE MATCH. Venues do list tennis derivatives beside the match-winner book — game spreads such as "A (-3.5) vs B (+3.5)" among them — and this API deliberately publishes none of them: a derivative is refused at the mapping step so it can never be served as, or beside, a match-winner price (2026-09-22).

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/markets \
  -H "Authorization: Bearer twjp_..."

GET /markets/{matchId}/prices

Market + recent price ticks per side, newest first (PRO)

Plan required: PRO · operationId: getMarketPrices

The mapped match-winner market for one match, with its recent price ticks per side, newest first. 404 with error: no_market (since 2026-09-02; match_id and coverage: "none" alongside) when no match-winner market is mapped to the match — a market is mapped only where one is published for that fixture, so a client walking every live match will meet this. A bare not_found means the match id itself does not exist. Every row of GET /matches carries has_market, so a slate can be filtered before any call here. GET /matches/{matchId} answers 200 for the same match with market and market_price set to null instead, and carries the live score in the same response, so a per-match poll built on the detail route never spends a call on a 404. Ticks are kept for 30 days and then deleted: a market older than that answers with an empty prices array while staying mapped — retention, not a fault. For paging past 500 ticks use /matches/{matchId}/prices with its cursor.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/markets/18953/prices \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/prices

Bare price ticks of the mapped match-winner market, newest first (PRO)

Plan required: PRO · operationId: listMatchPrices

Recent ticks only (no market wrapper). limit caps at 500; minutes bounds the lookback window; cursor pages an older match. 404 no_market when the match exists but has no mapped market (404 not_found for an unknown id). Retention (since 2026-09-15): in-play ticks of a match with a mapped market — from live to completion, plus a five-minute pad — are kept at full resolution and not deleted; pre-match / idle ticks and unmapped markets keep the tiers (every tick for an hour, ~1/minute to 24h, ~1/5 minutes after, deleted after 30 days). Ticks stamped before 2026-09-15 were already thinned under those tiers. Ticks are kept for 30 days and then deleted, so a match older than that answers an empty data while its market stays mapped — that is retention, not a fault. Past 500 ticks, page with the cursor: read a page, and while meta.has_more is true pass meta.next_cursor back as ?cursor= for the next (older) page. Pages never overlap or skip a tick (added 2026-09-09).

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/prices \
  -H "Authorization: Bearer twjp_..."

GET /history/matches/{matchId}/prices

Per-point price history — the match-winner quote in force at every played point (PRO)

Plan required: PRO · operationId: listHistoryMatchPrices

One row per played point of a match with a mapped market, ascending by seq (added 2026-09-15). Each row carries the score state the BASIC tape publishes and, per neutral side ("1" = players.p1's outcome, "2" = p2's), the newest quote observed at or before the point's capture time — or, when none precedes it, the first quote after it within five minutes (negative lag). A side with no usable quote is null, never invented. resolution is an honest label of the join: tick (|lag| <= 15 s), minute (<= 90 s), coarse (older); matches played from 2026-09-15 align against the full-resolution in-play tape, earlier ones against the thinned tape and read minute/coarse. The ULTRA-only per-point fields (server, winner, serve, outcome) are not on this surface. Works on a live match too. 404 no_market when the match has no mapped market — enumerate with GET /history/matches?has_market=true.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/matches/18953/prices \
  -H "Authorization: Bearer twjp_..."

GET /history/matches

Completed matches, newest first, with derived winner and tape coverage (BASIC)

Plan required: BASIC · operationId: listCompletedMatches

Requires BASIC on the live API, or any Historical Data API plan (Starter and up — see https://livetennisapi.com/historical-tennis-data-api). A FREE key may spend its 20 free history calls per calendar month here; past that the answer is 403 upgrade_required carrying free_history_taste: "used". All tours, January 2023 → now (deeper results live in the results archive, 1968–2022, at /history/archive/matches). Filter to a date range with from/to, and by tour, draw (singles/doubles), player (either participant) and country — same vocabulary as /matches. Each item carries a tape object saying what point-by-point data we hold for that match, so a whole page can be qualified in one call instead of one request per match. NOTE ?coverage= is applied AFTER the page is cut, so a filtered page is routinely shorter than limit (and may be empty) while later pages still hold matching matches — a short filtered page is not an end-of-data signal; ?points_complete= filters the same way. ?tier= (added 2026-09-22) selects by the level the tournament was played at in the match's season, and ?restated_since= (added 2026-09-22) keeps only the matches whose published result was corrected after an instant — the poll to run after each settlement pass.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/matches \
  -H "Authorization: Bearer twjp_..."

GET /history/coverage

Measured completeness rollup per tour × draw bucket (BASIC)

Plan required: BASIC · operationId: getHistoryCoverage

Requires BASIC on the live API, or any Historical Data API plan (Starter and up — see https://livetennisapi.com/historical-tennis-data-api). A FREE key may spend its 20 free history calls per calendar month here; past that the answer is 403 upgrade_required carrying free_history_taste: "used". The numbers to read BEFORE choosing what to backtest, in one call instead of paging the archive. A PREBUILT snapshot rebuilt nightly right after the completeness ledger reconverges — never computed at read time — so as_of (= built_at) dates every number, and ledger_max_computed_at is the newest underlying per-match measurement. Buckets are atp/wta/challenger/itf/juniors × singles/doubles plus other (team ties, mixed, exhibitions, and matches with no stated event type — counted, never dropped, so the totals cannot lie), derived from the same registries as the tour and draw fields. method states the full measurement rule in one paragraph, so every number carries its own definition. As of 2026-08-18 the headline spread it exposes: 51.1% of ITF singles matches are point-complete on the best basis against 3.5% of ITF doubles — do not extrapolate a completeness rate across a tour group.

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/coverage \
  -H "Authorization: Bearer twjp_..."

GET /history/matches/{matchId}

Per-match tape — point-by-point score + per-point model probabilities (BASIC)

Plan required: BASIC · operationId: getMatchTape

The tape is the point-by-point score sequence we hold for this match — every recorded score row including the model fields win_probability_p1 and danger at that point — plus match metadata and the model profiles produced during the match. The model fields here are part of the paid History product by design, distinct from the ULTRA-gated LIVE model fields. One match per request. Requires BASIC on the live API, or the Historical Data API Starter plan and up. The tape is NOT guaranteed to cover the whole match — check meta.coverage and meta.point_source before backtesting. Rows expanded after the fact from a finished-match point-by-point record carry a null timestamp and null model fields; nothing is ever synthesised. WORKS ON A LIVE MATCH, not only a completed one. The tape is assembled from whatever has been committed so far, so it is how you read the point-by-point history of a match in progress — including games played before you started watching, where we were already watching them. The LIST endpoint is completed-only; get live ids from /matches?status=live. /matches/{matchId}/score is one state; this is the sequence of states.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/matches/18953 \
  -H "Authorization: Bearer twjp_..."

GET /history/archive/matches

Results archive (1968–2022) — deep historical results (BASIC)

Plan required: BASIC · operationId: listArchiveMatches

Completed-match RESULTS from a licensed historical corpus — ATP and WTA main draws, qualifying/challengers and futures tiers, 1968 through 2022. Winner/loser-shaped records with final score, round, seeds, the players' ranks AT THE TIME, and per-match serve statistics where the era recorded them. Requires BASIC on the live API, or any Historical Data API plan (Starter and up). A SEPARATE id space from /matches — archive people are identified by the corpus person id and by name, never by roster player ids — and the archive ends where our own point-by-point coverage begins (2023-01), so no match is ever served from two datasets. event_date is the TOURNAMENT START date, the only date records of this era carry.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/archive/matches \
  -H "Authorization: Bearer twjp_..."

GET /history/archive/matches/{archiveId}

One archive result, with serve statistics where recorded (BASIC)

Plan required: BASIC · operationId: getArchiveMatch

Same entitlement as the archive listing. stats is null for the (mostly pre-1991) rows the source never recorded statistics for — never synthesised. A result played 2013–2022 may also have a reconstructed point-by-point tape at /history/archive/matches/{archiveId}/tape; the RESULT stays on BASIC either way.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/archive/matches/{archiveId} \
  -H "Authorization: Bearer twjp_..."

GET /history/archive/matches/{archiveId}/tape

Reconstructed 2013–2022 point-by-point tape for one archive result (ULTRA, or any History plan)

Plan required: ULTRA · operationId: getArchiveTape

The score sequence behind a 2013–2022 archive result, REBUILT FROM THE PUBLIC RECORD. The result tells you what happened; this tells you how. NOBODY WATCHED THESE MATCHES, and every field that would imply otherwise is null. timestamp is null on every row — not by convention, but because the production table has no timestamp column at all, so no repair, backfill or re-archive can put a wall clock on a 2016 row, and the promotion script refuses to run if such a column ever appears. win_probability_p1 and danger are null on every row: the model was not running in 2016 and nothing has been back-computed and served as if it had been (meta.model_rows and meta.observed_rows are both 0, always). profiles is always []. The rule we publish for the 2023+ tape — a non-null timestamp means we watched that point live — holds across both halves of the product. YEARS: 2013–2022 ONLY. 97,901 matches and 14,340,663 rows. The results archive holds a further 977,903 matches from 1968–2012 and NONE of them has a tape — there is no public point-by-point record of those years to rebuild and we do not manufacture one. A match with no tape answers 404, which is also the answer when a tape exists and failed the proof below; the two are deliberately not distinguished. COVERAGE OF THE ERA, thin spots beside the strong ones: 19.3% of archive matches played 2013–2022 overall, 44.9% of tour-level play. Main-draw tour buckets run 91.6–98.7% (ATP Masters 98.7%, ATP slam 98.0%, WTA Premier Mandatory 97.9%, WTA slam 97.4%, ATP 250–500 95.4%, WTA Premier 94.1%, WTA International 91.6%); ATP Challenger main draws 55.3% and Challenger qualifying 33.6%; slam QUALIFYING is thin at 16.0% (ATP) and 18.1% (WTA); ITF and futures are effectively absent — 25 of 116,575 ATP futures matches, 68 of 19,162 ITF M15, 48 of 9,380 ITF M25 — and this product does not cover them. If your work is ITF, this is the wrong dataset and we would rather you knew now. 31.0% of the corpus is qualifying-draw play, which is unusual at this scale and is the part you are least likely to hold already. HOW A TAPE IS BOUND TO ITS MATCH. A tape attached to the wrong match is silent, permanent and poisons anything trained on it, so each one proves five things before publication: the EDITION binds by majority vote onto one archive tournament; the NAMES resolve to exactly one archive row with an unambiguous orientation; the ROUND agrees through an explicit map (this is what separates the qualifying and main-draw meetings of the same pair inside one edition); the SET SPINE derived from the rows equals the published final score exactly (a retirement matches on a one-directional prefix rule — a tape may stop short, never run past the printed score); and the vendor DATE lies inside the tournament's window. The tape is then walked step by step against 23 interior invariants — games and sets never regress or jump, a closed set holds a score a set can actually finish on, a tiebreak is flagged only where one can be played, points never run backwards inside a game, seq is contiguous. A tape that fails any clause or any invariant is REFUSED WHOLESALE rather than published against a guess, which is why this endpoint answers 404 instead of serving a probable match. archiveId is an archive_matches.id (the id on a /history/archive/matches row), NOT a match id — the two are separate, overlapping integer spaces, so passing one to the other's routes resolves a different, real record without erroring. The response names it meta.archive_match_id for exactly that reason. Rows are WINNER-FIRST (sets[0] / games[0] / points[0] are the winner's, server: 1 means the winner was serving), unlike the p1/p2-shaped 2023+ tape — a live match has no winner while it is being played. This operation takes NO query parameters: sequence and points are ignored rather than refused. meta.sequence is always raw — a reconstructed tape has one source and no corrections, so there is nothing for a clean collapse to remove. Tier: core ULTRA, or any active History plan (Starter included, which opens it on a FREE core key). The archive RESULT itself (GET /history/archive/matches/{archiveId}) stays on BASIC — core BASIC and core PRO read the result and are refused the tape, and the refusal is 403 upgrade_required carrying capability: archive_tape. The per-year BULK files (?kind=archive_tape) are a separate gate: core ULTRA, or a History Pro/Business subscription, or an active one-off package window.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/archive/matches/{archiveId}/tape \
  -H "Authorization: Bearer twjp_..."

GET /history/archive/players

Archive player bios — hand, DOB, country, height, career-high (BASIC)

Plan required: BASIC · operationId: listArchivePlayers

People of the results archive (1968–2022), in their own id space — id is the corpus person id that archive match rows carry as winner.player_id / loser.player_id, scoped per tour; never a roster id. Career-high rank and the earliest week it was reached are computed offline from the corpus's own weekly ranking tables. Null fields are the era's silence, never guessed. Requires BASIC, or any Historical Data API plan.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/archive/players \
  -H "Authorization: Bearer twjp_..."

GET /history/archive/career

Career aggregates over the results archive, 1968–2022 (BASIC)

Plan required: BASIC · operationId: getArchiveCareer

One player's whole archive career in one response: W-L record (overall, by surface, by level, by year), titles, and the summed serve-stat block with derived ratios. Everything is a sum or a ratio of sums over rows you can fetch individually from /history/archive/matches — nothing is modelled. serve.matches_with_stats states the coverage honestly: the corpus records per-match serve statistics from 1991 only, so a 1970s career has a full W-L record and an empty serve block. Ambiguous name fragments are refused with candidates (same rule as /h2h); an unknown name is a 404. Requires BASIC, or any Historical Data API plan.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/archive/career \
  -H "Authorization: Bearer twjp_..."

GET /h2h

Head-to-head across the results archive (1968–2022) and our own completed matches (2023→now) (BASIC)

Plan required: BASIC · operationId: getHeadToHead

The record between two players, assembled from BOTH halves of the product: the results archive, where the winner is a stored column, and our own completed matches, where the winner is derived from the final recorded state. Names are the keys — archive people have no roster ids. A fragment matching more than one player is refused with the candidate list (400 ambiguous_name), because two people summed into one record is a wrong answer, not a convenience. Totals count meetings with a KNOWN winner; undecided counts the rest. Walkovers and retirements are part of the record, and each meeting carries outcome so you can exclude them. Requires BASIC, or any Historical Data API plan. On ULTRA, a per-player stats block adds serve/return/break-point aggregates over the pairing: archive_serve (serve-side, from 1991) and current (2023+, adding return and break-point conversion, aces and winners), each with meetings_with_stats.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/h2h \
  -H "Authorization: Bearer twjp_..."

GET /history/packages

List the pre-built monthly bulk history packages (PRO)

Plan required: PRO · operationId: listHistoryPackages

Bulk downloads are a heavier product than single-match tape reads. Requires PRO on the live API, or the Historical Data API Pro plan and up, or a one-off package access pass. A key that can read the tape but is not package-entitled receives 403 upgrade_required.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/packages \
  -H "Authorization: Bearer twjp_..."

GET /history/packages/{period}

One monthly package — manifest, or the bulk file itself (PRO)

Plan required: PRO · operationId: getHistoryPackage

Without format returns the package manifest (file set, counts, sha256). With format=jsonl or format=csv streams that file as an attachment. Same entitlement as /history/packages. 404 when the month has not been built yet — list available months first.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/packages/{period} \
  -H "Authorization: Bearer twjp_..."

GET /fixtures

Upcoming scheduled fixtures, earliest first (FREE)

Plan required: FREE · operationId: listFixtures

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/fixtures \
  -H "Authorization: Bearer twjp_..."

GET /usage

Your own usage vs quota (FREE — any tier)

Plan required: FREE · operationId: getUsage

Durable daily usage for the calling key: tier, limits, today's calls (current to the second) and a 30-day history. The per-minute window is on the X-RateLimit-* headers of every response, not here. Calls to this endpoint are quota-exempt — checking your usage never consumes it.

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/usage \
  -H "Authorization: Bearer twjp_..."

GET /rankings

Rankings and Elo — rank-ordered listing (PRO) or per-player as-of records (ULTRA); the as-of Elo tape is ULTRA in both modes

Plan required: PRO · operationId: listRankings

Returns, per ranking system, the newest record effective ON OR BEFORE as_of — never one dated after it. Every other ranking field in this API is the player's CURRENT value joined at read time, so replaying an old match elsewhere shows today's ranks; this endpoint is the point-in-time answer. Systems are never collapsed into a single "rank": ATP/WTA and the ITF circuits carry rank+points, UTR carries a rating with null rank and points because it has neither. meta.coverage.oldest_available gives the earliest date each system can answer for — ITF and UTR observations reach back to 2026-06-01 (append-only per-player history accumulates from 2026-07-29) and nothing earlier can be reconstructed. TWO MODES — with player ids (ULTRA) — the per-player point-in-time records described above. WITHOUT player (PRO) — the FULL published table in rank order for exactly one system, the newest week at or before as_of; rows carry player_name as published and a null player_id for players outside our roster, so the table has no silent holes. utr has no listing (a rating, not a ranking). SYSTEM=UTR — observed ratings, honestly bounded. UTR records are observed from UTR's public search: a rating UTR withholds appears as ABSENT, never as 0, and rating is the only populated value — rank and points are always null. Per-player as-of ONLY — there is deliberately no UTR listing, because a table of only the players we happen to track would be a fake leaderboard. Per-player history accumulates from 2026-07-29; scattered earlier single-snapshot observations reach back to 2026-06-01. Coverage is a deliberate bias, not a roster mirror: the 24-hour sweep targets players with no official rank and no Elo rating (so it skews ITF), and among players active in the last 60 days it holds 931 of 5,606 ITF players (16.6%), 197 of 1,903 Challenger (10.4%), 43 of 573 WTA (7.5%) and 15 of 525 ATP (2.9%) — measured 2026-08-17. SYSTEM=ELO — THE AS-OF ELO TAPE (ULTRA in BOTH modes). Our own computed Elo for 65,622 players on four independent ladders (overall, hard, clay, grass), back to 1877 (ATP) and 1968 (WTA), covering the main tours plus challengers plus the futures tier. It answers what a player was rated BEFORE a given match, which is the only shape a backtest can consume. It is a HISTORICAL TAPE rather than a live leaderboard — the corpus behind it is fixed and no longer receives new results, so meta.coverage.newest_available states the tape's head date on every response (2026-06-15 at publication), and you should read it before treating the table as current. A week's results become effective 14 days after that week begins — strictly after the longest event in tennis — so the failure direction is staleness, never look-ahead. rating is the Elo. rank is LISTING MODE ONLY and is null in per-player mode, because an Elo has no global rank at a past instant until you say which field and which activity window you mean. points is always null. matches is the count on THAT ladder, published so that a rating still near its 1500 cold start is visible rather than inferred. A ladder a player has never played is omitted, never substituted. Ratings are on our own scale, are not comparable with Elo published elsewhere, and do not decay — a surface played only a few weeks a year (grass in particular) moves slowly, so a rising player can sit below an established one for several seasons while beating them. A CURRENT per-player Elo remains free on GET /players/{id}; this is the point-in-time series, the leaderboard and the bulk export. That free rating is sourced differently and sits on a DIFFERENT scale — the two differ by roughly 150 Elo of per-player standard deviation — so never present a rating from one scale against a rating from the other. The Elo listing REQUIRES tour — the ATP and WTA walks are disjoint, so a combined leaderboard would not be comparable — and takes exactly one surface (default overall). elo is never implicit — omitting system returns the official systems only.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/rankings \
  -H "Authorization: Bearer twjp_..."

GET /rally/matches

Charted matches with shot-by-shot data (ULTRA)

Plan required: ULTRA · operationId: listRallyMatches

Charted matches, newest first. RALLY CONSTRUCTION IS THE LAYER BELOW THE TAPE: the tape says what the score became after each point, this says how the point was played. It has its OWN id space. The charted corpus and our own match table are different populations — the corpus reaches back decades and concentrates on the biggest events, while our matches begin when our own collection did. Keying this on our match ids would hide most of it. Ask this endpoint for the authoritative coverage list rather than assuming a match is charted: charting is human work, so coverage is deep, not universal.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/rally/matches \
  -H "Authorization: Bearer twjp_..."

GET /rally/matches/{rallyMatchId}

Rally construction for one charted match (ULTRA)

Plan required: ULTRA · operationId: getRallyMatch

One charted match with its points, in play order. Paged with limit/offset; meta.total is the match's full point count.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/rally/matches/{rallyMatchId} \
  -H "Authorization: Bearer twjp_..."

GET /history/matches/{matchId}/rally

Rally construction by OUR match id (ULTRA)

Plan required: ULTRA · operationId: getMatchRally

Rally construction addressed by OUR match id, resolved through the optional link. Answers 404 {"error":"not_charted"} when we hold the match but nobody charted it — deliberately distinct from "no such match", because most of our matches are not charted and a consumer walking the archive must tell them apart.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/matches/18953/rally \
  -H "Authorization: Bearer twjp_..."

GET /charting/players

Career shot-level charting aggregate for one player (ULTRA)

Plan required: ULTRA · operationId: getChartingPlayer

The deepest serve/return profile we hold, from the Match Charting Project: serve placement (deuce/ad × wide/body/T), return depth and outcomes, net and serve-and-volley conversion, clutch break/game/set-point serving and returning, winners and unforced errors by wing, and rally-length and shot-direction tendencies — summed over the player's charted matches. name (min 3 chars) is the key; a fragment matching more than one charted person is refused with the candidate list, and gender=men|women disambiguates. Every field is a raw SUM over the player's Total rows and matches_charted states the sample. COVERAGE IS CURATED — 11,803 charted matches across both tours back to the 1960s, concentrated on the majors, NOT full-slate coverage.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/charting/players \
  -H "Authorization: Bearer twjp_..."

GET /charting/matches/{chartingMatchId}

One charted match, every stat family for both players (ULTRA)

Plan required: ULTRA · operationId: getChartingMatch

Every Match Charting Project stat family for one charted match, both players, with the per-set split (row/set 1, 2, Total) exactly as charted. chartingMatchId is this product's own id space (1960–2026, mostly matches with no counterpart in the live table).

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/charting/matches/{chartingMatchId} \
  -H "Authorization: Bearer twjp_..."

POST /webhooks

Register an outbound webhook (ULTRA, direct keys only)

Plan required: ULTRA · operationId: createWebhook

We POST the same frames the WebSocket sends to your HTTPS endpoint on every live score commit. Up to 3 webhooks per key (409 webhook_limit past that). The response is the ONLY time the signing secret is shown — store it. Each delivery carries X-LTAPI-Signature (sha256=<hex> — HMAC-SHA256 of the RAW request body with your webhook secret; verify with a constant-time compare), X-LTAPI-Timestamp (Unix seconds at send time — reject stale replays at your edge) and X-LTAPI-Event (the frame type: score, break_point, break_point_result or point). Delivery is best-effort, at-most-once, no replay: one attempt per frame with a ~3s timeout and redirects disabled. Every score frame is the complete current score, so a missed delivery self-corrects on the next commit. A point frame is an EVENT, not a state — a missed one does NOT self-correct; recover it with GET /matches/{matchId}/points?after_seq= and dedup by seq. After 25 consecutive failures the webhook is disabled automatically (enabled:false, last_error set — visible in GET /webhooks); delete and re-register to resume.

Responses

Example

curl https://api.livetennisapi.com/api/public/v1/webhooks \
  -H "Authorization: Bearer twjp_..."

GET /webhooks

List your webhooks (ULTRA, direct keys only; never includes the secret)

Plan required: ULTRA · operationId: listWebhooks

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/webhooks \
  -H "Authorization: Bearer twjp_..."

DELETE /webhooks/{webhookId}

Remove one of your webhooks (ULTRA, direct keys only)

Plan required: ULTRA · operationId: deleteWebhook

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/webhooks/{webhookId} \
  -H "Authorization: Bearer twjp_..."

GET /ws-token

Mint a connection token for the high-fan-out push feed (ULTRA)

Plan required: ULTRA · operationId: createWsToken

Returns a short-lived signed token plus the push WebSocket URL and the channel vocabulary: match:{match_id} per-match streams and slate:all for every live score frame. Frames are the same allowlist score objects the polling endpoints return. This is a separate surface from the native /ws feed described above — same ULTRA gate, built for high fan-out (no shared connection ceiling), and the recommended home for continuous/production streaming. The endpoint speaks the **Centrifugo client protocol** (v2, JSON). Easiest path: the official Python (livetennisapi ≥ 1.4.0) and JS (≥ 1.5.0) SDKs ship a built-in PushStream client — no extra dependency. Raw protocol, if you prefer your own client: (1) open a WebSocket to ws_url; (2) send {"connect": {"token": "<token>"}, "id": 1} — the token goes INSIDE this JSON frame, never as a raw first message; (3) subscribe per channel with {"subscribe": {"channel": "slate:all"}, "id": 2}; (4) publications arrive as {"push": {"channel": ..., "pub": {"data": <frame>}}}; (5) the server's heartbeat is an empty JSON object {} — reply with {} promptly or you will be disconnected. Messages may batch several newline-delimited JSON objects. Tokens are short-lived and the connection closes around token expiry: mint a fresh token on EVERY reconnect and re-subscribe. The channels object lists only channels that will actually deliver for your key right now (a channel name in this response is a promise). Where enabled server-side, additional channel families appear: point:match:{match_id} / point:slate (per-point events), listed — as point_match / point_slate in the vocabulary — only for keys whose plan carries the point surface, and signal:match:{match_id} / signal:slate (derived break_point, break_point_result and divergence events, and since 2026-09-12 the stoppage family: medical_timeout_start/end, trainer_called/_end, toilet_break_start/end, stoppage_start/end, pause_start/end). A family absent from the response will not deliver for your key right now. Deliberately separate channels: a slate:all subscriber asked for score states and never starts receiving events unasked. Point and signal frames are events, not states — a missed point does NOT self-correct on the next frame; recover it via GET /matches/{matchId}/points?after_seq= and dedup by seq.

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/ws-token \
  -H "Authorization: Bearer twjp_..."