Skip to content
datasportsAPI

FixturesPlay by play

Documentation

/

Type to filter the docs by title or path.

FixturesEndpoint 9 of 116

Play by play

GET

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

Plan
Pro + Business
Auth
Bearer dsa_live_…
Parameters
1 required · 0 optional
Returns
PlayByPlayEntry[]
Try in Playground

Text commentary from our data source, one entry per action, oldest first. It covers football — cards, shots, corners, substitutions and more, keyed by minute — and basketball — each basket, free throw, rebound, foul and turnover, with the game clock, running score, the basket’s value and its location on the court.

Plan access

Requires a Pro or Business plan; every other plan receives 403 endpoint_not_in_plan.

Worth knowing

  • 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.

01Parameters

  • idpathRequired

    fixture id issued by DataSportsAPI, a positive integer

02Request

The same call from the command line and each SDK. The SDK lines assume a client created with your key; left out, it is read from DATASPORTSAPI_API_KEY. Installing a client: SDKs & CLI.

curl -H "Authorization: Bearer dsa_live_…" \
    "https://api.datasportsapi.com/v2/fixtures/{id}/play-by-play"

03Response

The top-level keys of the JSON body. Each object links to its full shape in the data reference.

data
PlayByPlayEntry[]
meta
count
ObjectsPlayByPlayEntry
Example response
{ "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 } }

04Errors

  • 403history_not_in_plan

    kick-off falls before the start of your plan’s history window

Any key can also meet401unauthorized429rate_limited429quota_exceeded500internal_errorEvery error code