---
title: "Get all matches"
method: GET
path: "/basketball/matches"
tags: ["Basketball.Matches"]
---

# Get all matches

`GET /basketball/matches`

## Request

- Base URL: `https://sports.highlightly.net`
- URL: `https://sports.highlightly.net/basketball/matches`
- Auth: none declared. Required headers: `x-rapidapi-host`, `x-rapidapi-key`
- TypeScript: <https://skmtc.dev/highlightly/apis/sports-api-highlightly/docs/basketball/matches/get.ts> (a function with typed inputs; its response is checked against the schema)

> Refresh interval: Once a minute

> Route returns only general match information. For additional match details check the `matches/{matchId}` route. 

Retrieve a list of matches based on the requested query parameters. 

At least one primary query parameter needs to be specified before you can retrieve the data (`timezone`, `limit`, `offset` are considered secondary).

You can specify the `timezone` field in combination with the `date` query parameter to get matches relevant to your location.

There are two other important parameters. The `limit` parameter defines what the number of returned matches will be. If the number of actual matches is above the `limit` value you can make subsequent requests by increasing the `offset` value. 

Matches have different possible states they can be in:

| State        | Description |
| -----------  | ----------- |
| Not started    |  Match has not been started yet.         |
| First quarter  |  Match is considered in play and is in the first period.         |
| Second quarter  | Match is considered in play and is in the second period.          |
| Third quarter  |  Match is considered in play and is in the third period.          |
| Fourth quarter  |  Match is considered in play and is in the fourth period.          |
| Over time  | Game was considered a draw in normal time. Additional extra time is needed to decide the winner.          |
| Break time  | Regulation period between quarters or over time.          |
| Half time  | Half time pause between second and third quarter.          |
| Finished  | Match has been concluded.          |
| Finished after over time  | Match has been concluded in over time.         |
| Postponed  | Match has been postponed due to certain circumstances that are preventing the game from being played. Event start time will be changed to a moment in the future.           |
| Cancelled  |  Game will not be played.         |
| Suspended  |  Match has already been in play but was suspended. In the future the game will resume from the exact point where it was halted.         |
| Awarded  |  Game awarded to one of the teams when the other forfeits or specific circumstances have been met such as insufficient players, late arrival, team withdrawl, etc.          |
| Abandoned  | Considered "abandoned" when it is prematurely ended by the officials and can not be resumed or completed. In the future the game **might be** resumed from the exact point where it was halted.            |
| Unknown  | Unknown match coverage or state.          |
| To be announced  | Match's start time will be updated or competing teams are not yet known.          |

Below is an example of what you can aim to achieve with the matches endpoint:

![Basketball matches example](https://highlightly.net/assets/img/documentation/basketball/matches.png)

## Query parameters

- `leagueName` string
- `leagueId` number
- `date` string
- `timezone` string
- `season` number
- `homeTeamId` number
- `awayTeamId` number
- `homeTeamName` string
- `awayTeamName` string
- `countryCode` string
- `countryName` string
- `limit` number
- `offset` number

## Headers

- `x-rapidapi-host` string, required
- `x-rapidapi-key` string, required

## Response `200`

- BasketballMatchPaginatedResponseDto
  - `data` BasketballMatchResponseDto[], required
    - `id` number, required
    - `week` string
    - `stage` string, required
    - `date` string, required
    - `country` BasketballCountryResponseDto, required
      - `code` string, required: Country code specified by the ISO 3166 standard.
      - `name` string, required
      - `logo` string, required
    - `awayTeam` BasketballTeamResponseDto, required
      - `id` number, required
      - `logo` string
      - `name` string, required
    - `homeTeam` BasketballTeamResponseDto, required
      - `id` number, required
      - `logo` string
      - `name` string, required
    - `league` BasketballMatchLeagueResponseDto, required
      - `id` number, required
      - `season` number, required
      - `name` string, required
      - `logo` string
    - `state` BasketballMatchStateResponseDto, required
      - `description` 'Not started' | 'First quarter' | 'Second quarter' | 'Third quarter' | 'Fourth quarter' | 'Over time' | 'Break time' | 'Half time' | 'Finished' | 'Finished after over time' | 'Postponed' | 'Cancelled' | 'Suspended' | 'Awarded' | 'Abandoned' | 'Unknown' | 'To be announced', required: State of the match.
      - `clock` number: Current minute of the current period.
      - `score` BasketballMatchScoreResponseDto, required
        - `current` string: Home - Away score for the match. Includes overtime as well.
        - `q1` string: Home - Away score in 1st quarter.
        - `q2` string: Home - Away score in 2nd quarter.
        - `q3` string: Home - Away score in 3rd quarter.
        - `q4` string: Home - Away score in 4th quarter.
        - `overTime` string: Home - Away score in overtime.
  - `pagination` PaginationResponseDto, required
    - `totalCount` number, required: Available number of items, relevant to the provided query.
    - `offset` number, required
    - `limit` number, required
  - `plan` PlanResponseDto, required
    - `tier` string, required: Your current API subscription tier.
    - `message` string, required: Explanation message regarding your current tier.

## Other responses

- `400`: Bad request descriptive error.
- `500`: Internal server error.

---

[API](https://skmtc.dev/highlightly/apis/sports-api-highlightly.md) - [All operations](https://skmtc.dev/highlightly/apis/sports-api-highlightly/llms.txt) - [OpenAPI document](https://skmtc.dev/highlightly/apis/sports-api-highlightly/revisions/c8a366d3091f?raw)