> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportrix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /matches — List and Filter Matches by League

> GET /matches and GET /matches/active return paginated match lists. Filter by status, date range, and more. Requires the fixtures scope.

The matches endpoints let you browse and filter the fixture schedule. Use `GET /matches` for the full schedule within a league with optional filters, `GET /matches/active` to see only live and upcoming matches in a league, `GET /matches/live` for every in-play match across a sport, or `GET /matches/{match_id}` to fetch a single match by its id.

## Endpoints

```text theme={null}
GET https://api.sportrixdata.com/api/matches
GET https://api.sportrixdata.com/api/matches/active
GET https://api.sportrixdata.com/api/matches/live
GET https://api.sportrixdata.com/api/matches/{match_id}
```

## Authentication and Scope

All three endpoints require the `fixtures` scope. Include your API key in the `X-API-Key` header.

***

## GET /matches

Returns all matches for a league, with optional filters for status and time window.

### Query Parameters

<ParamField query="league" type="integer" required>
  The league id to list matches for. Obtain this value from [`GET /leagues`](/api/leagues).
</ParamField>

<ParamField query="status" type="string">
  Filter by match status. Must be one of `NOT_STARTED`, `STARTED`, `CLOSE_OF_PLAY`, or `FINISHED`. Omit to return matches of all statuses. `CLOSE_OF_PLAY` is the multi-day cricket Test "between days" state — see the [match object](/api/match-object) for details.
</ParamField>

<ParamField query="start_after" type="datetime">
  Only return matches with a `start_time` at or after this timestamp. ISO 8601 UTC, e.g. `2026-06-18T00:00:00Z`.
</ParamField>

<ParamField query="start_before" type="datetime">
  Only return matches with a `start_time` at or before this timestamp. ISO 8601 UTC.
</ParamField>

<ParamField query="limit" type="integer">
  Number of matches to return per page. Default `100`, maximum `200`. Values above 200 are clamped to 200.
</ParamField>

<ParamField query="offset" type="integer">
  Number of matches to skip before returning results. Default `0`.
</ParamField>

***

## GET /matches/active

Returns matches that are live or upcoming for a league — status of `NOT_STARTED`, `STARTED`, or `CLOSE_OF_PLAY` (a multi-day cricket Test between days).

### Query Parameters

<ParamField query="league" type="integer" required>
  The league id to list active matches for.
</ParamField>

<ParamField query="limit" type="integer">
  Page size. Default `100`, maximum `200`.
</ParamField>

<ParamField query="offset" type="integer">
  Number of matches to skip. Default `0`.
</ParamField>

***

## GET /matches/live

Returns every currently in-play match for a sport, across all of its leagues — `STARTED` matches plus cricket Tests at `CLOSE_OF_PLAY` (between days, still ongoing). Useful for a "what's live right now" view without iterating leagues. This endpoint is **not paginated** — live matches are a naturally bounded set, and the response is a plain array of match objects. A sport outside your allowlist returns `[]`.

### Query Parameters

<ParamField query="sport" type="integer" required>
  Sport id. Must be in your allowlist. Obtain this value from [`GET /sports`](/api/sports).
</ParamField>

***

## GET /matches/{match_id}

Returns a single match by its id.

### Path Parameter

<ParamField path="match_id" type="integer" required>
  The match id. Obtain this from any `/matches` or `/matches/active` response.
</ParamField>

***

## Match Object Fields

<ResponseField name="id" type="integer">
  Match id. Use this value as `match_id` when calling [`GET /matches/{id}/live`](/api/live) or [`GET /matches/{id}/result`](/api/result).
</ResponseField>

<ResponseField name="home_team" type="string">
  Name of the home team.
</ResponseField>

<ResponseField name="away_team" type="string">
  Name of the away team.
</ResponseField>

<ResponseField name="start_time" type="datetime">
  Scheduled kick-off time in ISO 8601 UTC format (e.g. `2026-06-18T02:00:00Z`).
</ResponseField>

<ResponseField name="status" type="string">
  Current match status: `NOT_STARTED`, `STARTED`, `CLOSE_OF_PLAY` (multi-day cricket Test between days), or `FINISHED`. See the [match object](/api/match-object) for details.
</ResponseField>

***

## Example Requests

```bash theme={null}
# All matches in a league
curl "https://api.sportrixdata.com/api/matches?league=172&limit=2" \
  -H "X-API-Key: $KEY"

# Only upcoming and live matches
curl "https://api.sportrixdata.com/api/matches/active?league=172" \
  -H "X-API-Key: $KEY"

# All in-play matches across a sport
curl "https://api.sportrixdata.com/api/matches/live?sport=1" \
  -H "X-API-Key: $KEY"

# Single match by id
curl "https://api.sportrixdata.com/api/matches/41301" \
  -H "X-API-Key: $KEY"
```

## Example Response

`GET /matches` and `GET /matches/active` return a [pagination envelope](/concepts/pagination):

```json theme={null}
{
  "items": [
    {
      "id": 41301,
      "home_team": "Salmon Bay FC (W)",
      "away_team": "West Seattle Rhodies FC (W)",
      "start_time": "2026-06-18T02:00:00Z",
      "status": "NOT_STARTED"
    }
  ],
  "total": 1,
  "limit": 2,
  "offset": 0,
  "count": 1,
  "page": 1,
  "total_pages": 1,
  "has_more": false
}
```

`GET /matches/live` returns a plain array of match objects (no pagination envelope):

```json theme={null}
[
  {
    "id": 41282,
    "home_team": "Vancouver Whitecaps II",
    "away_team": "The Town",
    "start_time": "2026-06-18T01:00:00Z",
    "status": "STARTED"
  }
]
```

`GET /matches/{match_id}` returns the match object directly, without an envelope.

<Note>
  `GET /matches/{match_id}` returns `404` for matches that are outside your account's enabled sports allowlist, in addition to matches that do not exist or are suspended/postponed.
</Note>