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

Group: Fixtures

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.

Plans: Requires Pro, Business or Enterprise; a Free or Starter key receives 403 endpoint_not_in_plan.

Note: 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

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | yes | fixture id issued by DataSportsAPI, a positive integer |

## Response

- `data`: `PlayByPlayEntry[]`
- `meta`: count
- Objects: PlayByPlayEntry (https://datasportsapi.com/markdown/reference.md#playbyplayentry)

## Errors

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

Plus the common errors (https://datasportsapi.com/markdown/docs.md#errors).

## Request

cURL:

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

TypeScript:

```ts
const { data, meta } = await client.fixtures.playByPlay(id);
```

Python:

```python
res = client.fixtures.play_by_play(id)
```

Go:

```go
res, err := client.Fixtures.PlayByPlay(ctx, id)
```

CLI:

```bash
$ dsa fixtures play-by-play <id>
```

## Example response

```json
{ "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 } }
```

---

Base URL: https://api.datasportsapi.com. Authenticate each /v2 call with the header `Authorization: Bearer <key>` (secret keys begin with `sk_live_`).
HTML: https://datasportsapi.com/docs/fixtures/play-by-play/ · All docs: https://datasportsapi.com/markdown/docs.md · Data reference: https://datasportsapi.com/markdown/reference.md
