Skip to content

Livematches in play

Demo: Matchboard, opens in a new tab
Docs v2

Fixtures

Play by play

GET

/v2/fixtures/{id}/play-by-play

Pro and up

View as MarkdownTry in Playground →

Text commentary from the source, one action per entry, oldest first, in football (cards, shots, corners, substitutions and more, by minute) and basketball (each basket, free throw, rebound, foul and turnover). Basketball entries also give the game clock, the running score, the basket’s value and its location on the court.

The English text is produced by the source’s data provider and is separate from our AI commentary, which lives at /commentary. type is a closed enum, with other covering anything we have not mapped. Each entry includes every field, null where it does not apply: football uses minute / addedMinute; basketball uses periodSecond (seconds gone in the period), periodSecondsLeft (what the game clock shows), at, position / zone on the court, and scoreType on scoreChange; homeScore / awayScore appear on scoreChange (and on a football penaltyScored, carried forward from the previous goal). If the source has no commentary, the array is empty.

Parameters

id

pathrequired

fixture id issued by DataSportsAPI, a positive integer

Response

meta
count
errors
403 history_not_in_plan — kick-off falls before the start of your plan’s history window

Any /v2 call can also come back with one of the common errors.

curl -H "Authorization: Bearer sk_live_…" \
    "https://api.datasportsapi.com/v2/fixtures/{id}/play-by-play"
Example
{ "data": [
  { "type": "yellowCard", "side": "home", "period": "period1", "minute": 45, "addedMinute": 6,
    "periodSecond": null, "periodSecondsLeft": null, "at": null,
    "text": "Lewis Cook (Bournemouth) is shown the yellow card for a bad foul.",
    "player": null, "assist": null, "playerIn": null, "playerOut": null, "drawnBy": null, "stolenBy": null,
    "goalkeeper": null, "homeScore": null, "awayScore": null, "scoreType": null, "position": null, "zone": null } ],
  "meta": { "count": 1 } }

// Basketball:
{ "data": [ …,
  { "type": "scoreChange", "side": "away", "period": "period4", "minute": null, "addedMinute": null,
    "periodSecond": 700, "periodSecondsLeft": 20, "at": "2026-10-22T01:54:25.605Z",
    "text": "Jalen Johnson makes regular free throw 2 of 2",
    "player": { "id": 123, "name": "Jalen Johnson", "slug": null, "shortName": null, "image": "https://cdn.datasportsapi.com/v2/players/123/photo" },
    "assist": null, "playerIn": null, "playerOut": null, "drawnBy": null, "stolenBy": null, "goalkeeper": null,
    "homeScore": 125, "awayScore": 132, "scoreType": "freeThrow", "position": null, "zone": null } ],
  "meta": { "count": 486 } }