---
title: "Get all matches"
method: GET
path: "/nba/matches"
tags: ["NBA, NCAAB.Matches"]
---

# Get all matches

`GET /nba/matches`

## Request

- Base URL: `https://sports.highlightly.net`
- URL: `https://sports.highlightly.net/nba/matches`
- Auth: none declared. Required headers: `x-rapidapi-host`, `x-rapidapi-key`
- TypeScript: <https://skmtc.dev/highlightly/apis/sports-api-highlightly/docs/nba/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 |
| -----------  | ----------- |
| 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.           |
| 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.         |
| Cancelled  |  Game will not be played.         |
| 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.            |
| Finished  | Match has been concluded.          |
| Scheduled    |  Match has not been started yet.         |
| End period  |  Break time between periods.         |
| Half time  | Half time pause between second and third quarter.          |
| In progress  | Game is currently in progress.         |
| Unknown  | Unknown match coverage or state.          |

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

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

## Query parameters

- `league` string
- `date` string
- `timezone` string
- `season` number
- `homeTeamId` number
- `awayTeamId` number
- `homeTeamName` string
- `awayTeamName` string
- `homeTeamAbbreviation` string
- `awayTeamAbbreviation` string
- `homeTeamDisplayName` string
- `awayTeamDisplayName` string
- `limit` number
- `offset` number

## Headers

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

## Response `200`

- NbaMatchPaginatedResponseDto
  - `data` NbaMatchResponseDto[], required
    - `id` number, required
    - `league` 'NBA' | 'NCAA', required
    - `season` number, required
    - `state` NbaMatchStateResponseDto, required
      - `clock` number, required: Time left for a game to finish.
      - `score` NbaMatchScoreResponseDto, required
        - `awayTeam` number[], required: Current away team result for each inning.
        - `homeTeam` number[], required: Current home team result for each inning.
      - `period` number, required: Current period
      - `description` 'Suspended' | 'Postponed' | 'Cancelled' | 'Abandoned' | 'Finished' | 'Scheduled' | 'In progress' | 'End period' | 'Half time' | 'Unknown', required: Current game state description
    - `homeTeam` NbaTeamInfoResponseDto, required
      - `id` number, required
      - `displayName` string, required
      - `name` string, required
      - `logo` string
      - `abbreviation` string, required
    - `awayTeam` NbaTeamInfoResponseDto, required
      - `id` number, required
      - `displayName` string, required
      - `name` string, required
      - `logo` string
      - `abbreviation` string, required
    - `date` string, required
  - `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)