# GET /v2/fixtures

Group: Fixtures

Fixtures starting on one UTC date, for a single league, one category (country, region or tour, all its leagues at once), one country in a sport, or a whole sport paged ten leagues at a time by league rank.

Plans: Every plan, Free included.

Note: Need a single country’s schedule, amateur and youth competitions included? Pass category= (take the id from that day’s /v2/fixtures/counts?sport= or from /v2/categories), or combine sport= with country=; either returns everything in one request rather than paging through the sport. When only sport is set, keep requesting pages until hasNextPage is false. All pages except the final one contain 10 leagues, so an empty page tells you the day is exhausted; a page may still carry fewer fixtures than leagues, because a league whose matches sit just outside the UTC day adds nothing. The set of fixtures for a date is cached — for minutes on today and future dates, for hours on past dates, and permanently once every fixture has finished — whereas the status, score and clock of a live fixture are accurate to the second (details in Data freshness). If you need a live feed, /v2/livescores or the WebSocket is the better fit.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `date` | query | yes | UTC date as YYYY-MM-DD, from 1990-01-01 to one year in the future |
| `sport` | query | no | sport slug; mandatory when neither league nor category is set |
| `league` | query | no | league id — returns only that league’s fixtures for the date, on a single page (page has to be 0) |
| `category` | query | no | category id, as listed by /v2/categories or /v2/fixtures/counts — all leagues of that country, region or tour for the date, sorted by start time, on a single page (page has to be 0). Available since 2026-11-04 |
| `country` | query | no | two-letter Country.code (EN, ES, US …; case-insensitive), used together with sport — returns the date’s fixtures from that country’s categories in the sport, on a single page. Available since 2026-11-04 |
| `page` | query | no | only when sport is the sole filter: page index 0–99 (defaults to 0), each page covering 10 leagues |

## Response

- `data`: `Fixture[]`
- `meta`: date, page, count, hasNextPage; the league filter adds league (and sport when passed), with page fixed at 0 and hasNextPage false; the category filter adds category (and sport when passed), single page; the country filter adds sport, country, categoryIds (the categories that were queried), complete; sport on its own adds sport, leagueCount (number of leagues on this page), complete (false if some league lists were temporarily unavailable — try again shortly)
- Objects: Fixture (https://datasportsapi.com/markdown/reference.md#fixture)

## Errors

- 400 bad_request — date absent or malformed, sport not recognised, no sport / league / category supplied, country sent without sport, two or more of league / category / country combined, page outside 0–99, or a non-zero page alongside league, category or country
- 404 not_found — no category with that id exists in DataSportsAPI
- 503 upstream_unavailable — not a single league list on the page could be retrieved

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?date=…"
```

TypeScript:

```ts
const { data, meta } = await client.fixtures.list({ date });
for await (const page of client.fixtures.listPages({ date })) { … }
```

Python:

```python
res = client.fixtures.list(date=date)
for page in client.fixtures.list_pages(date=date): ...
```

Go:

```go
res, err := client.Fixtures.List(ctx, &datasportsapi.FixturesListParams{Date: date})
for page, err := range client.Fixtures.ListPages(ctx, &datasportsapi.FixturesListParams{Date: date}) { … }
```

CLI:

```bash
$ dsa fixtures list <date>
$ dsa fixtures list <date> --all -o csv
```

## Example response

```json
$ curl -H "Authorization: Bearer sk_live_…" "https://api.datasportsapi.com/v2/fixtures?date=2026-10-18&sport=football"

{ "data": [ { "id": 201324, "sport": "football", "status": { "type": "finished", … },
    "startTime": "2026-10-18T15:30:00.000Z", "league": { "id": 195828, "name": "Premier League", … }, … }, … ],
  "meta": { "date": "2026-10-18", "sport": "football", "page": 0, "count": 38, "leagueCount": 10,
            "hasNextPage": true, "complete": true } }
```

---

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