Live tennis scores API

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. WITHDRAWN STATES (since 2026-09-23). When the legality gate behind this read refuses a state a stream has already published, the verdict object on the score says so: kind, superseded_sequence, reason and safe_to_resume. It is null on an ordinary read. The push feed, the WebSocket and webhooks carry the same judgement as a score_withdrawn frame naming the same sequence, so a stream consumer learns a state was taken back without polling. GET /history/incidents is the published register of data-quality incidents. THE RECOVERY PATH (since 2026-09-25). A consumer that missed the frame cannot get the live verdict back, because it is recomputed over the newest state and returns null as soon as the next state is accepted. Every withdrawal is now recorded durably when the judgement is made: pass ?sequence=N here to have verdict answer for the sequence you hold, and read GET /matches/{matchId}/withdrawals for the whole record on a match, including the frame exactly as the feed sent it. 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 /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}/withdrawals

The durable record of every score state we withdrew on this match (ULTRA)

Plan required: ULTRA · operationId: getMatchWithdrawals

Added 2026-09-25. One row per refused sequence, oldest first, each carrying the score_withdrawn frame exactly as the push feed sent it. This is the RECOVERY PATH for a missed frame. The verdict object on GET /matches/{matchId}/score is recomputed on every read over the newest state, so it returns null again as soon as the next state is accepted, which in a live match is seconds. The record here is written when the judgement is made, before the frame is delivered, so a consumer that was disconnected can still learn that a sequence it holds was taken back. GET /matches?withdrawn_since= says which matches to ask about; ?sequence=N on the score read answers for one sequence without fetching the list. ULTRA, the tier that receives the frame on the push feed and the native WebSocket. An empty data is the ordinary answer and means nothing was withdrawn on that match. Records are kept 90 days from the withdrawal.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/withdrawals \
  -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 /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_..."