# GET /v2/fixtures/{id}/tracking/ball

Group: Tracking data

Ball positions recorded live for a football or tennis match, oldest first, on Enterprise only: about 14 positions per minute of football play on the 0–100 pitch, about one per tennis shot, measured in millimetres from the net. Each call returns up to limit frames recorded after since; to read on, send meta.next as the next since.

Plans: Requires the Enterprise plan; every other plan receives 403 endpoint_not_in_plan.

Note: Basketball, ice hockey and matches the source does not follow have no ball track, so the list comes back empty. To poll a match in progress, send the at of the newest frame you already hold as since. The tracking:{id} channel is the alternative: it pushes each frame within about a second.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | yes | fixture id issued by DataSportsAPI, a positive integer |
| `since` | query | no | return only frames recorded after this instant (ISO-8601 with any offset; the instant itself is excluded) — meta.next from the previous page, or the at of your newest frame |
| `limit` | query | no | frames per page, 1–5000 (5000 if omitted, enough for a whole football match) |

## Response

- `data`: `BallFrame[]`
- `meta`: count, hasNextPage, next (the since value for the following page, or null)
- Objects: BallFrame (https://datasportsapi.com/markdown/reference.md#ballframe)

## Errors

- 400 bad_request — since or limit is malformed
- 403 endpoint_not_in_plan — returned on every plan except Enterprise
- 404 not_found — DataSportsAPI never issued this id

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}/tracking/ball"
```

TypeScript:

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

Python:

```python
res = client.tracking.ball(id)
```

Go:

```go
res, err := client.Tracking.Ball(ctx, id, &datasportsapi.TrackingBallParams{})
```

CLI:

```bash
$ dsa tracking ball <id>
```

## Example response

```json
{ "data": [ { "at": "2026-11-11T20:05:31.412Z", "x": 61.5, "y": 38.2 }, { "at": "2026-11-11T20:05:35.906Z", "x": 70.1, "y": 44 }, … ],
  "meta": { "count": 1384, "hasNextPage": false, "next": null } }
```

---

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/tracking/ball/ · All docs: https://datasportsapi.com/markdown/docs.md · Data reference: https://datasportsapi.com/markdown/reference.md
